> ## 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
> Retrieve the API secret for a partner-issued OAuth API key once. The secret is unrecoverable after retrieval.
## 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.]
## 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}`
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`
````