> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve OAuth API key secret
> The endpoint retrieves the API secret for a partner-issued API key. The endpoint returns the secret exactly once per key — a subsequent call returns `409 Conflict`.
**Required scope:** `apikeys.read`.
**Region availability:** The endpoint is available on the global server (`https://whitebit.com`) only.
Store the API secret in encrypted backend storage on first retrieval. The secret is not recoverable after this call returns.
## Authentication
OAuth 2.0 Bearer token. Required scope: `apikeys.read`. See [Authentication](/api-reference/authentication). The endpoint is available on `https://whitebit.com` only.
## Cache
No caching. The response carries `Cache-Control: no-store`.
## Notes
Store the API secret in encrypted backend storage on first retrieval. The secret is not recoverable after this call returns.
The endpoint returns the secret exactly once per key. A subsequent call for the same key returns `409 Conflict`. Recovery from `409` requires deleting the key via [Delete OAuth API key](/api-reference/oauth/usage/api-key-delete) and restarting the OAuth API key flow to issue a new key — the secret cannot be re-issued for an existing key.
A `423 Locked` response indicates a concurrent secret-retrieval attempt against the same key. Retry the request after a short delay. Use exponential backoff starting at 5–10 seconds, doubling per attempt, capped at 60 seconds, with a total budget of 3–5 minutes. The platform does not currently send a `Retry-After` header.
* Obtain the `externalId` path parameter from [Check OAuth API key existence](/api-reference/oauth/usage/api-key-info).
* The endpoint does not return the public `apiKey` string. The WhiteBIT frontend delivers the public `apiKey` to the partner at consent completion. \[PENDING: confirm with the WhiteBIT frontend team where exactly the partner receives the public `apiKey` (callback parameter name and URL location) — update this note with the wire-level details once confirmed.]
## Used in these guides
* [Copy Trading](/guides/copy-trading) — mirror a lead trader's orders into followers' own accounts via OAuth-issued keys.
* [Fast API Key integration](/guides/fast-api-key-integration) — OAuth-issued API keys created on behalf of end users.
## OpenAPI
````yaml openapi/oauth2.yaml GET /oauth2/api-key/{externalId}/secret
openapi: 3.0.3
info:
title: OAuth 2.0 API Reference
description: WhiteBIT OAuth 2.0 API for authentication and account management
version: 1.0.0
servers:
- url: https://whitebit.com
description: WhiteBIT Global Server
- url: https://whitebit.eu
description: WhiteBIT EU Server
security: []
tags:
- name: Authentication
description: >
OAuth 2.0 authentication endpoints for obtaining and refreshing access
tokens.
Available Scopes (requested during client setup):
- general: General API access
- show.userinfo: Access to basic user information
- users.read: Read user data
- users.email.read: Read user email information
- users.kyc.read: Information about whether a user has passed KYC
verification
- orders.read: Read trading orders
- orders.create: Create trading orders
- orders.delete: Delete trading orders
- balances.read: Read account balances
- markets.read: Read market information
- deals.read: Read trading deals
- orders_history.read: Read order history
- users.transactions.read: Read user transactions
- users.converts.read: Read currency conversion history
- users.balances.read: Read user account balances
- users.orders.read: Read user orders
- users.deals.read: Read user deals
- apikeys.create: Issue an OAuth-bound API key during the consent flow
- apikeys.read: Read OAuth-issued API key state and retrieve its secret
once
- apikeys.delete: Delete an OAuth-issued API key linked to the partner
- name: Account Endpoints
description: >-
Endpoints for retrieving account information, balances, and transaction
history
- name: OAuth API Keys
description: >
Partner-facing endpoints for managing API keys created via the OAuth API
key flow.
Available on the global server (`https://whitebit.com`) only. The EU
server (`https://whitebit.eu`) does not expose these endpoints in this
release.
Required scopes:
- `apikeys.read` for `GET /oauth2/api-key/info` and `GET
/oauth2/api-key/{externalId}/secret`
- `apikeys.delete` for `DELETE /oauth2/api-key/{externalId}`
A third scope, `apikeys.create`, authorizes key creation on the WhiteBIT
consent screen and is not consumed by any endpoint here. Holding at least
one of the three admits an OAuth2 client to the flow.
paths:
/oauth2/api-key/{externalId}/secret:
get:
tags:
- OAuth API Keys
summary: Retrieve OAuth API key secret
description: >
The endpoint retrieves the API secret for a partner-issued API key. The
endpoint returns the secret exactly once per key — a subsequent call
returns `409 Conflict`.
**Required scope:** `apikeys.read`.
**Region availability:** The endpoint is available on the global server
(`https://whitebit.com`) only.
Store the API secret in encrypted backend storage on first retrieval.
The secret is not recoverable after this call returns.
parameters:
- name: externalId
in: path
required: true
description: >-
External UUID of the API key. Obtain the value from `GET
/oauth2/api-key/info`.
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
responses:
'200':
description: Successful response. The secret is returned exactly once.
headers:
Cache-Control:
description: Always `no-store` to prevent the secret from being cached.
schema:
type: string
example: no-store
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
apiSecret:
type: string
description: >-
The API secret. Persist immediately in encrypted
backend storage — the secret is not recoverable.
example: YOUR_API_SECRET
'401':
description: >-
Missing or invalid Bearer token, or token does not carry the
`apikeys.read` scope.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
message:
type: array
items:
type: string
example:
- Unauthorized.
'403':
description: >-
The key does not belong to the authenticated OAuth2 client, or the
key is not a partner-issued key.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
message:
type: array
items:
type: string
example:
- Forbidden.
'404':
description: Key not found.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
message:
type: array
items:
type: string
example:
- Key not found.
'409':
description: >-
The secret has already been retrieved for this key. Recovery
requires deleting the key and restarting the OAuth API key flow.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
message:
type: array
items:
type: string
example:
- Secret already retrieved.
'423':
description: >-
A concurrent secret-retrieval attempt holds the lock. Retry after a
short delay.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
message:
type: array
items:
type: string
example:
- Temporary lock, retry shortly.
security:
- BearerAuth: []
servers:
- url: https://whitebit.com
description: WhiteBIT Global Server
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
OAuth 2.0 Bearer Token authentication. Include the access token in the
Authorization header.
Example: `Authorization: Bearer YOUR_ACCESS_TOKEN`
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.