Retrieve an OAuth access token, to be used for authentication of 'private' requests.

📖 Related Article: Authentication

Authentication Methods:

Three methods of authentication are supported (selected with grant_type):

• client_credentials - Using the client id and client secret that can be found on the API page on the website. This is the simplest method, suitable for server-to-server applications and quick setup.

• client_signature - Enhanced security method using a cryptographic signature instead of sending the client secret directly. The signature is calculated over <timestamp>\n<nonce>\n<data> (the three values joined with line-feed characters, timestamp exactly as sent). Keys with a shared secret use an HMAC-SHA256 signature encoded as hexadecimal; asymmetric (RSA / Ed25519) keys use a digital signature over the same string encoded as URL-safe base64 without padding. This method requires client_id, timestamp and signature; nonce and data are optional (nonce is strongly recommended for replay protection). See the Client Signature (WebSocket) guide for detailed signature calculation instructions.

• refresh_token - Using a refresh token that was received from an earlier invocation. This allows you to obtain a new access token without re-supplying your Client ID and Client Secret. Best for long-lived sessions, token renewal, and avoiding re-authentication.

Refresh token behavior:

• Every successful refresh issues a new access token and a new refresh token, and invalidates the previously issued token pair. Always store the newest refresh_token; reusing an older one fails with -32602 (invalid token), which also affects concurrent refreshes with the same token.
• The scope parameter is ignored for this grant type: the new tokens keep the scope, session and lifetime of the original token.
• A token with connection scope is bound to the connection it was issued on and cannot be refreshed or used from another connection.

Scope behavior (client_credentials and client_signature):

• Without a session: or connection scope item, a WebSocket request gets a connection scope token. An HTTP (REST) request gets a session scope token with a generated rest-... session name, unless connection was requested explicitly.
• connection and session:name cannot be combined (-32602).
• Requested permission scopes (trade, wallet, account, block_trade, block_rfq) never exceed the permissions of the API key: higher levels are silently reduced to the key's level, and permission scopes that are not requested inherit the key's permissions. This is not reported as an error.

Response:

The response will contain an access token, expiration period (number of seconds that the token is valid) and a refresh token that can be used to get a new set of tokens. Over WebSocket, a successful call also authenticates the current connection, so later private requests on it need no access_token.

Errors (JSON-RPC error.code):

• 13004 invalid_credentials - unknown client_id, wrong client_secret, invalid signature, or client_id longer than 16 bytes.
• 13009 unauthorized - timestamp outside the allowed window, nonce longer than 128 bytes or already used, connecting IP not in the key's IP whitelist (reason: bad_ip).
• -32602 Invalid params - missing required parameter for the chosen grant_type, unknown grant_type, invalid scope, or an invalid / expired / already-replaced refresh_token (including session_not_found).

Try in API console

{
  "result": {
    "access_token": "843SehgeX5n6XxEU4XbABx4Cny5Akai5iHiJePTsvUw7",
    "expires_in": 31536000,
    "refresh_token": "6faf8L36JdaSqsjCEEiwqifPpj6JB18RWwiWHrsGTZ91",
    "mandatory_tfa_status": "enabled"
  }
}