> For the complete documentation index, see [llms.txt](https://docs.gobtcpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gobtcpay.com/api-reference/merchant-api/merchant-auth.md).

# Merchant Auth

Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context.

## Log in

> Authenticates with \`email\` and \`password\`. Returns either an authenticated session (\`tokens\`, \`user\`, \`memberships\`) when \`$case\` is \`authenticated\`, or an \`mfaToken\` to complete via 2FA when \`$case\` is \`mfa\_required\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/login":{"post":{"summary":"Log in","description":"Authenticates with `email` and `password`. Returns either an authenticated session (`tokens`, `user`, `memberships`) when `$case` is `authenticated`, or an `mfaToken` to complete via 2FA when `$case` is `mfa_required`.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"password":{"type":"string"}},"required":["email","password"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"anyOf":[{"type":"object","properties":{"$case":{"type":"string","const":"authenticated"},"tokens":{"type":"object","properties":{"accessToken":{"type":"string","description":"Short-lived JWT access token. Send it as `Authorization: Bearer <accessToken>` on authenticated requests."},"refreshToken":{"type":"string","description":"Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair."},"expiresAt":{"type":"integer","minimum":0,"description":"Expiry time as a Unix timestamp (seconds)."}},"required":["accessToken","refreshToken","expiresAt"],"additionalProperties":false},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"displayName":{"type":["string","null"],"description":"Public display name shown to payers (optional)."},"avatarUrl":{"type":["string","null"]},"twoFactorEnabled":{"type":"boolean"},"status":{"type":"string","enum":["active","blocked","pending"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","email","emailVerified","displayName","avatarUrl","twoFactorEnabled","status"],"additionalProperties":false},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"merchantName":{"type":"string","description":"Merchant's internal name."},"role":{"type":"string","enum":["admin","manager"]},"status":{"type":"string","enum":["active","invited","revoked"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","merchantId","merchantName","role","status"],"additionalProperties":false}}},"required":["$case","tokens","user","memberships"],"additionalProperties":false},{"type":"object","properties":{"$case":{"type":"string","const":"mfa_required"},"mfaToken":{"type":"string"}},"required":["$case","mfaToken"],"additionalProperties":false}]}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Register

> Creates a new merchant user from \`email\` and \`password\`, with optional \`displayName\` and \`merchantName\` (bootstraps the first merchant with the user as admin). Returns the new \`userId\` and \`status\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/register":{"post":{"summary":"Register","description":"Creates a new merchant user from `email` and `password`, with optional `displayName` and `merchantName` (bootstraps the first merchant with the user as admin). Returns the new `userId` and `status`.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"password":{"type":"string"},"displayName":{"type":"string","description":"Public display name shown to payers (optional)."},"merchantName":{"type":"string","description":"Merchant's internal name."}},"required":["email","password"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"userId":{"type":"string"},"status":{"type":"string","enum":["active","blocked","pending"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["userId","status"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Refresh tokens

> Exchanges a valid \`refreshToken\` for a fresh \`tokens\` bundle (\`accessToken\`, \`refreshToken\`, \`expiresAt\`).

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/refresh":{"post":{"summary":"Refresh tokens","description":"Exchanges a valid `refreshToken` for a fresh `tokens` bundle (`accessToken`, `refreshToken`, `expiresAt`).","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refreshToken":{"type":"string","description":"Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair."}},"required":["refreshToken"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"tokens":{"type":"object","properties":{"accessToken":{"type":"string","description":"Short-lived JWT access token. Send it as `Authorization: Bearer <accessToken>` on authenticated requests."},"refreshToken":{"type":"string","description":"Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair."},"expiresAt":{"type":"integer","minimum":0,"description":"Expiry time as a Unix timestamp (seconds)."}},"required":["accessToken","refreshToken","expiresAt"],"additionalProperties":false}},"required":["tokens"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Log out

> Revokes the given \`refreshToken\`, or the current session if omitted. Returns \`{ ok }\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/logout":{"post":{"summary":"Log out","description":"Revokes the given `refreshToken`, or the current session if omitted. Returns `{ ok }`.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refreshToken":{"type":"string","description":"Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair."}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Current user

> Returns the authenticated \`user\` profile and the list of \`memberships\` linking the user to merchants with a role.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/me":{"post":{"summary":"Current user","description":"Returns the authenticated `user` profile and the list of `memberships` linking the user to merchants with a role.","tags":["Merchant Auth"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"displayName":{"type":["string","null"],"description":"Public display name shown to payers (optional)."},"avatarUrl":{"type":["string","null"]},"twoFactorEnabled":{"type":"boolean"},"status":{"type":"string","enum":["active","blocked","pending"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","email","emailVerified","displayName","avatarUrl","twoFactorEnabled","status"],"additionalProperties":false},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"merchantName":{"type":"string","description":"Merchant's internal name."},"role":{"type":"string","enum":["admin","manager"]},"status":{"type":"string","enum":["active","invited","revoked"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","merchantId","merchantName","role","status"],"additionalProperties":false}},"walletLinked":{"type":"boolean","description":"Whether a receiving wallet is linked to the active merchant. The UI uses this to gate onboarding."},"walletAddress":{"type":["string","null"],"description":"The linked receiving wallet address, or null when none is linked."}},"required":["user","memberships","walletLinked","walletAddress"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Verify email

> Confirms an email address using the \`email\` and the emailed \`code\`. On success the user is signed in: returns the full auth bundle (\`tokens\`, \`user\`, \`memberships\`) so the client can log straight into the merchant cabinet without a separate login.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/verify-email":{"post":{"summary":"Verify email","description":"Confirms an email address using the `email` and the emailed `code`. On success the user is signed in: returns the full auth bundle (`tokens`, `user`, `memberships`) so the client can log straight into the merchant cabinet without a separate login.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"code":{"type":"string"}},"required":["email","code"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"tokens":{"type":"object","properties":{"accessToken":{"type":"string","description":"Short-lived JWT access token. Send it as `Authorization: Bearer <accessToken>` on authenticated requests."},"refreshToken":{"type":"string","description":"Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair."},"expiresAt":{"type":"integer","minimum":0,"description":"Expiry time as a Unix timestamp (seconds)."}},"required":["accessToken","refreshToken","expiresAt"],"additionalProperties":false},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"displayName":{"type":["string","null"],"description":"Public display name shown to payers (optional)."},"avatarUrl":{"type":["string","null"]},"twoFactorEnabled":{"type":"boolean"},"status":{"type":"string","enum":["active","blocked","pending"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","email","emailVerified","displayName","avatarUrl","twoFactorEnabled","status"],"additionalProperties":false},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"merchantName":{"type":"string","description":"Merchant's internal name."},"role":{"type":"string","enum":["admin","manager"]},"status":{"type":"string","enum":["active","invited","revoked"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","merchantId","merchantName","role","status"],"additionalProperties":false}}},"required":["tokens","user","memberships"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## OAuth login

> Logs in via an OAuth \`provider\` using \`authCode\` or \`idToken\` (with optional \`redirectUri\`); \`merchantName\` bootstraps the first merchant for new accounts. Returns an authenticated session or an \`mfaToken\` challenge.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/oauth/login":{"post":{"summary":"OAuth login","description":"Logs in via an OAuth `provider` using `authCode` or `idToken` (with optional `redirectUri`); `merchantName` bootstraps the first merchant for new accounts. Returns an authenticated session or an `mfaToken` challenge.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["apple","google"]},"authCode":{"type":"string"},"idToken":{"type":"string"},"redirectUri":{"type":"string"},"merchantName":{"type":"string","description":"Merchant's internal name."}},"required":["provider"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"anyOf":[{"type":"object","properties":{"$case":{"type":"string","const":"authenticated"},"tokens":{"type":"object","properties":{"accessToken":{"type":"string","description":"Short-lived JWT access token. Send it as `Authorization: Bearer <accessToken>` on authenticated requests."},"refreshToken":{"type":"string","description":"Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair."},"expiresAt":{"type":"integer","minimum":0,"description":"Expiry time as a Unix timestamp (seconds)."}},"required":["accessToken","refreshToken","expiresAt"],"additionalProperties":false},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"displayName":{"type":["string","null"],"description":"Public display name shown to payers (optional)."},"avatarUrl":{"type":["string","null"]},"twoFactorEnabled":{"type":"boolean"},"status":{"type":"string","enum":["active","blocked","pending"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","email","emailVerified","displayName","avatarUrl","twoFactorEnabled","status"],"additionalProperties":false},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"merchantName":{"type":"string","description":"Merchant's internal name."},"role":{"type":"string","enum":["admin","manager"]},"status":{"type":"string","enum":["active","invited","revoked"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","merchantId","merchantName","role","status"],"additionalProperties":false}}},"required":["$case","tokens","user","memberships"],"additionalProperties":false},{"type":"object","properties":{"$case":{"type":"string","const":"mfa_required"},"mfaToken":{"type":"string"}},"required":["$case","mfaToken"],"additionalProperties":false}]}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Change password

> Sets \`newPassword\` for the current user; \`oldPassword\` is required unless setting a password for the first time. Returns \`{ ok }\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/password/change":{"post":{"summary":"Change password","description":"Sets `newPassword` for the current user; `oldPassword` is required unless setting a password for the first time. Returns `{ ok }`.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"oldPassword":{"type":"string"},"newPassword":{"type":"string"}},"required":["newPassword"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Forgot password

> Triggers a password-reset email for the given \`email\`. Always returns \`{ ok }\` to avoid account enumeration.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/password/forgot":{"post":{"summary":"Forgot password","description":"Triggers a password-reset email for the given `email`. Always returns `{ ok }` to avoid account enumeration.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"}},"required":["email"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Reset password

> Sets \`newPassword\` using a reset \`token\` from the password-reset email. Returns \`{ ok }\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/password/reset":{"post":{"summary":"Reset password","description":"Sets `newPassword` using a reset `token` from the password-reset email. Returns `{ ok }`.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"newPassword":{"type":"string"}},"required":["token","newPassword"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Verify 2FA

> Completes an MFA login challenge with the \`mfaToken\` and a TOTP or recovery \`code\`. Returns an authenticated session (\`tokens\`, \`user\`, \`memberships\`).

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/2fa/verify":{"post":{"summary":"Verify 2FA","description":"Completes an MFA login challenge with the `mfaToken` and a TOTP or recovery `code`. Returns an authenticated session (`tokens`, `user`, `memberships`).","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mfaToken":{"type":"string"},"code":{"type":"string"}},"required":["mfaToken","code"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"tokens":{"type":"object","properties":{"accessToken":{"type":"string","description":"Short-lived JWT access token. Send it as `Authorization: Bearer <accessToken>` on authenticated requests."},"refreshToken":{"type":"string","description":"Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair."},"expiresAt":{"type":"integer","minimum":0,"description":"Expiry time as a Unix timestamp (seconds)."}},"required":["accessToken","refreshToken","expiresAt"],"additionalProperties":false},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"displayName":{"type":["string","null"],"description":"Public display name shown to payers (optional)."},"avatarUrl":{"type":["string","null"]},"twoFactorEnabled":{"type":"boolean"},"status":{"type":"string","enum":["active","blocked","pending"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","email","emailVerified","displayName","avatarUrl","twoFactorEnabled","status"],"additionalProperties":false},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"merchantName":{"type":"string","description":"Merchant's internal name."},"role":{"type":"string","enum":["admin","manager"]},"status":{"type":"string","enum":["active","invited","revoked"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","merchantId","merchantName","role","status"],"additionalProperties":false}}},"required":["tokens","user","memberships"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Set up TOTP

> Begins TOTP enrollment, returning the \`secret\`, \`otpauthUri\`, and a \`qr\` data URI for the authenticator app. TOTP is not active until confirmed via enable.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/2fa/totp/setup":{"post":{"summary":"Set up TOTP","description":"Begins TOTP enrollment, returning the `secret`, `otpauthUri`, and a `qr` data URI for the authenticator app. TOTP is not active until confirmed via enable.","tags":["Merchant Auth"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"secret":{"type":"string"},"otpauthUri":{"type":"string"},"qr":{"type":"string","description":"QR code as a data URI"}},"required":["secret","otpauthUri","qr"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Enable TOTP

> Activates TOTP by confirming a \`code\` from the authenticator. Returns one-time \`recoveryCodes\` shown only once.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/2fa/totp/enable":{"post":{"summary":"Enable TOTP","description":"Activates TOTP by confirming a `code` from the authenticator. Returns one-time `recoveryCodes` shown only once.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"recoveryCodes":{"type":"array","items":{"type":"string"}}},"required":["recoveryCodes"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Disable TOTP

> Disables TOTP after re-authenticating with a current TOTP \`code\` or the account \`password\`. Returns \`{ ok }\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/2fa/totp/disable":{"post":{"summary":"Disable TOTP","description":"Disables TOTP after re-authenticating with a current TOTP `code` or the account `password`. Returns `{ ok }`.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"password":{"type":"string"}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Passkey register options

> Returns WebAuthn \`publicKeyOptions\` (PublicKeyCredentialCreationOptions incl. challenge) to pass to \`navigator.credentials.create()\` for registering a new passkey.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/passkey/register/options":{"post":{"summary":"Passkey register options","description":"Returns WebAuthn `publicKeyOptions` (PublicKeyCredentialCreationOptions incl. challenge) to pass to `navigator.credentials.create()` for registering a new passkey.","tags":["Merchant Auth"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"publicKeyOptions":{"description":"PublicKeyCredentialCreationOptions JSON, including challenge"}},"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Passkey register verify

> Verifies the authenticator attestation \`credential\` (with optional \`deviceLabel\`) and stores the passkey. Returns the created \`credential\` descriptor.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/passkey/register/verify":{"post":{"summary":"Passkey register verify","description":"Verifies the authenticator attestation `credential` (with optional `deviceLabel`) and stores the passkey. Returns the created `credential` descriptor.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credential":{"description":"PublicKeyCredential attestation JSON from the authenticator"},"deviceLabel":{"type":"string"}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"credential":{"type":"object","properties":{"id":{"type":"string"},"deviceLabel":{"type":["string","null"]},"createdAt":{"type":"integer","minimum":0,"description":"Creation time as a Unix timestamp (seconds)."},"lastUsedAt":{"anyOf":[{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"},{"type":"null"}]}},"required":["id","deviceLabel","createdAt","lastUsedAt"],"additionalProperties":false}},"required":["credential"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Passkey login options

> Returns WebAuthn \`publicKeyOptions\` (PublicKeyCredentialRequestOptions incl. challenge) for \`navigator.credentials.get()\`. Pass \`email\` for a specific user, or omit for discoverable (usernameless) login.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/passkey/login/options":{"post":{"summary":"Passkey login options","description":"Returns WebAuthn `publicKeyOptions` (PublicKeyCredentialRequestOptions incl. challenge) for `navigator.credentials.get()`. Pass `email` for a specific user, or omit for discoverable (usernameless) login.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"publicKeyOptions":{"description":"PublicKeyCredentialRequestOptions JSON, including challenge"}},"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Passkey login verify

> Verifies the authenticator assertion \`credential\` and signs the user in (single-step, no extra MFA). Returns an authenticated session (\`tokens\`, \`user\`, \`memberships\`).

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/passkey/login/verify":{"post":{"summary":"Passkey login verify","description":"Verifies the authenticator assertion `credential` and signs the user in (single-step, no extra MFA). Returns an authenticated session (`tokens`, `user`, `memberships`).","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credential":{"description":"PublicKeyCredential assertion JSON from the authenticator"}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"tokens":{"type":"object","properties":{"accessToken":{"type":"string","description":"Short-lived JWT access token. Send it as `Authorization: Bearer <accessToken>` on authenticated requests."},"refreshToken":{"type":"string","description":"Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair."},"expiresAt":{"type":"integer","minimum":0,"description":"Expiry time as a Unix timestamp (seconds)."}},"required":["accessToken","refreshToken","expiresAt"],"additionalProperties":false},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"displayName":{"type":["string","null"],"description":"Public display name shown to payers (optional)."},"avatarUrl":{"type":["string","null"]},"twoFactorEnabled":{"type":"boolean"},"status":{"type":"string","enum":["active","blocked","pending"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","email","emailVerified","displayName","avatarUrl","twoFactorEnabled","status"],"additionalProperties":false},"memberships":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."},"merchantName":{"type":"string","description":"Merchant's internal name."},"role":{"type":"string","enum":["admin","manager"]},"status":{"type":"string","enum":["active","invited","revoked"],"description":"Current status. Payments: `initiated` / `paid` / `failed` / `expired` / `canceled` / `cleared`. Payment transactions: `success` / `failed` / `pending` / `cleared`."}},"required":["id","merchantId","merchantName","role","status"],"additionalProperties":false}}},"required":["tokens","user","memberships"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## List passkeys

> Returns the current user's registered passkeys as \`items\`, each with \`id\`, \`deviceLabel\`, \`createdAt\`, and \`lastUsedAt\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/passkey/list":{"post":{"summary":"List passkeys","description":"Returns the current user's registered passkeys as `items`, each with `id`, `deviceLabel`, `createdAt`, and `lastUsedAt`.","tags":["Merchant Auth"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"deviceLabel":{"type":["string","null"]},"createdAt":{"type":"integer","minimum":0,"description":"Creation time as a Unix timestamp (seconds)."},"lastUsedAt":{"anyOf":[{"type":"integer","minimum":0,"description":"UnixTime (seconds since epoch)"},{"type":"null"}]}},"required":["id","deviceLabel","createdAt","lastUsedAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Delete passkey

> Removes the passkey identified by \`credentialId\` from the current user. Returns \`{ ok }\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/passkey/delete":{"post":{"summary":"Delete passkey","description":"Removes the passkey identified by `credentialId` from the current user. Returns `{ ok }`.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credentialId":{"type":"string"}},"required":["credentialId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## List sessions

> Lists the current user's active sessions as \`items\` (with \`userAgent\`, \`ip\`, timestamps, and \`current\` flag) plus \`totalCount\`. Accepts optional \`pagination\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/sessions/list":{"post":{"summary":"List sessions","description":"Lists the current user's active sessions as `items` (with `userAgent`, `ip`, timestamps, and `current` flag) plus `totalCount`. Accepts optional `pagination`.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"type":"object","properties":{"limit":{"type":"number","minimum":1,"maximum":100,"default":20},"skip":{"type":"number","minimum":0,"default":0}},"additionalProperties":false}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"userAgent":{"type":["string","null"]},"ip":{"type":["string","null"]},"createdAt":{"type":"integer","minimum":0,"description":"Creation time as a Unix timestamp (seconds)."},"expiresAt":{"type":"integer","minimum":0,"description":"Expiry time as a Unix timestamp (seconds)."},"current":{"type":"boolean"}},"required":["id","userAgent","ip","createdAt","expiresAt","current"],"additionalProperties":false}},"totalCount":{"type":"number","description":"Total number of records matching the filters."}},"required":["items","totalCount"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Revoke session

> Revokes the session identified by \`sessionId\`. Returns \`{ ok }\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/sessions/revoke":{"post":{"summary":"Revoke session","description":"Revokes the session identified by `sessionId`. Returns `{ ok }`.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Switch merchant

> Switches the active merchant context to \`merchantId\`, returning fresh \`tokens\` carrying the new merchantId/role claims.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/context/switch":{"post":{"summary":"Switch merchant","description":"Switches the active merchant context to `merchantId`, returning fresh `tokens` carrying the new merchantId/role claims.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchantId":{"type":"string","description":"Identifier of the merchant (UUID)."}},"required":["merchantId"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"tokens":{"type":"object","properties":{"accessToken":{"type":"string","description":"Short-lived JWT access token. Send it as `Authorization: Bearer <accessToken>` on authenticated requests."},"refreshToken":{"type":"string","description":"Long-lived JWT refresh token. Use it at **Refresh access tokens** to obtain a new token pair."},"expiresAt":{"type":"integer","minimum":0,"description":"Expiry time as a Unix timestamp (seconds)."}},"required":["accessToken","refreshToken","expiresAt"],"additionalProperties":false}},"required":["tokens"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Link xpub key (via link token)

> Links a BIP32 extended public key (\`xpub\`) to the merchant account, authorized by the one-time \`linkToken\` from \*\*Start wallet link\*\* (read from the scanned QR) — no bearer auth required. Receiving addresses are later derived from this key along its \`derivationPath\`. Optionally pass the \`masterFingerprint\` (for PSBT key origins) and a \`label\`. Returns the stored key record with its \`keyId\`. For the signed-in dashboard flow, use \*\*Link xpub key (authorized)\*\*.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[],"paths":{"/merchant/auth/xpub/link":{"post":{"summary":"Link xpub key (via link token)","description":"Links a BIP32 extended public key (`xpub`) to the merchant account, authorized by the one-time `linkToken` from **Start wallet link** (read from the scanned QR) — no bearer auth required. Receiving addresses are later derived from this key along its `derivationPath`. Optionally pass the `masterFingerprint` (for PSBT key origins) and a `label`. Returns the stored key record with its `keyId`. For the signed-in dashboard flow, use **Link xpub key (authorized)**.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"linkToken":{"type":"string","description":"One-time link token from **Start wallet link**, read from the scanned QR. Scopes the call to the merchant's link session (no bearer auth needed)."},"xpub":{"type":"string","description":"BIP32 extended public key (xpub/ypub/zpub) to link to the merchant account."},"derivationPath":{"type":"string","description":"Base derivation path the xpub is exported at (e.g. `m/84'/0'/0'`); receiving addresses derive from it."},"masterFingerprint":{"type":"string","description":"Master key fingerprint (8 hex chars), used in PSBT key origins so signers can match derived inputs."},"label":{"type":"string","description":"Optional human-readable label for the linked key."}},"required":["linkToken","xpub"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"keyId":{"type":"string","description":"Id of the stored linked-key record."},"xpub":{"type":"string","description":"BIP32 extended public key (xpub/ypub/zpub) to link to the merchant account."},"derivationPath":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Base derivation path the xpub is exported at (e.g. `m/84'/0'/0'`); receiving addresses derive from it."},"masterFingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Master key fingerprint (8 hex chars), used in PSBT key origins so signers can match derived inputs."},"label":{"type":["string","null"],"description":"Optional human-readable label for the linked key."},"linkedAt":{"type":"integer","minimum":0,"description":"When the key was linked, Unix timestamp (seconds)."}},"required":["keyId","xpub","derivationPath","masterFingerprint","label","linkedAt"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```

## Link xpub key (authorized)

> Authenticated counterpart of \*\*Link xpub key (via link token)\*\*: links an \`xpub\` to the active merchant identified by the bearer token, so no \`linkToken\` is needed. Same \`derivationPath\`, \`masterFingerprint\`, and \`label\` options; returns the stored key record with its \`keyId\`.

```json
{"openapi":"3.1.0","info":{"title":"GoBTC Pay Merchant Account API","version":"1.45.2"},"tags":[{"name":"Merchant Auth","description":"Merchant dashboard sign-in: email/password, OAuth, passkeys, TOTP 2FA, sessions, token refresh, and switching the active merchant context."}],"servers":[{"url":"https://api.gobtcpay.com/public/api/v1.1"}],"security":[{"merchantAuth":[]}],"components":{"securitySchemes":{"merchantAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Merchant dashboard access token obtained from `/merchant/auth/login` (or the OAuth / passkey / 2FA login flows). Send it as `Authorization: Bearer <accessToken>`. Refresh it via `/merchant/auth/refresh` when it expires."}}},"paths":{"/merchant/auth/xpub/link-authorized":{"post":{"summary":"Link xpub key (authorized)","description":"Authenticated counterpart of **Link xpub key (via link token)**: links an `xpub` to the active merchant identified by the bearer token, so no `linkToken` is needed. Same `derivationPath`, `masterFingerprint`, and `label` options; returns the stored key record with its `keyId`.","tags":["Merchant Auth"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"xpub":{"type":"string","description":"BIP32 extended public key (xpub/ypub/zpub) to link to the merchant account."},"derivationPath":{"type":"string","description":"Base derivation path the xpub is exported at (e.g. `m/84'/0'/0'`); receiving addresses derive from it."},"masterFingerprint":{"type":"string","description":"Master key fingerprint (8 hex chars), used in PSBT key origins so signers can match derived inputs."},"label":{"type":"string","description":"Optional human-readable label for the linked key."}},"required":["xpub"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"result":{"type":"object","properties":{"$case":{"type":"string","const":"success"},"success":{"type":"object","properties":{"keyId":{"type":"string","description":"Id of the stored linked-key record."},"xpub":{"type":"string","description":"BIP32 extended public key (xpub/ypub/zpub) to link to the merchant account."},"derivationPath":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Base derivation path the xpub is exported at (e.g. `m/84'/0'/0'`); receiving addresses derive from it."},"masterFingerprint":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Master key fingerprint (8 hex chars), used in PSBT key origins so signers can match derived inputs."},"label":{"type":["string","null"],"description":"Optional human-readable label for the linked key."},"linkedAt":{"type":"integer","minimum":0,"description":"When the key was linked, Unix timestamp (seconds)."}},"required":["keyId","xpub","derivationPath","masterFingerprint","label","linkedAt"],"additionalProperties":false}},"required":["$case","success"],"additionalProperties":false}},"required":["id","result"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"500":{"description":"Error response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"statusCode":{"type":"number","description":"Numeric error status code."},"description":{"type":"string","description":"Human-readable description."},"statusMessage":{"type":"string","description":"Short machine-readable error message."}},"required":["statusCode","description","statusMessage"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.gobtcpay.com/api-reference/merchant-api/merchant-auth.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.