Skip to navigation
REST API EndpointsAuthentication

Access Token Request

View as Markdown

Request an access token using your credentials and API Key.

Available to: Anyone with valid API credentials (no access token required)

Environments: Demo, Live

Rate Limit: 5 requests per hour, 15-second back-off, counts failed requests only

Exchange your credentials for an access token, then send that token with the Bearer scheme on subsequent requests. Provide your name and password, your application identifiers (appId, appVersion, deviceId), and your API Key (cid and sec). On success, the response includes an accessToken and its expirationTime, plus an mdAccessToken for market data requests.

A successful request starts a tracked session. Mind the token lifetime and session limits:

  • An access token lasts about 90 minutes — the exact moment is in expirationTime. Extend it by calling renewAccessToken about 15 minutes before it expires, rather than requesting a new token.
  • You’re limited to two concurrent sessions per user; a third closes the oldest. Use a dedicated API user and centralize token issuance, sharing one token across dependent services.

See Authentication & Access for the full walkthrough and session guidance.

Common Failure Scenarios

  • The name/password or API Key (cid/sec) is incorrect.
  • Too many failed attempts trigger a time penalty: the response carries p-ticket and p-time, and you can retry after p-time seconds. When p-captcha is true, retry from a third-party application is blocked for about an hour.

Error Messages

errorTextTrigger
Non-empty errorTextThe request failed; the field describes the reason (for example, invalid credentials).

Request

This endpoint expects an object.
namestringRequired<=64 characters
passwordstringRequired<=512 characters
hibpCheckbooleanOptional
appIdstringOptional<=64 characters
appVersionstringOptional<=64 characters
deviceIdstringOptional<=64 characters
cidstringOptional<=64 characters
secstringOptional<=8192 characters

Response

AccessTokenResponse
errorTextstringOptional<=8192 characters

Non-empty if the request failed

hibpHintenumOptional
EmailAndPasswordCompromised, PasswordCompromised
Allowed values:
accessTokenstringOptional<=8192 characters
expirationTimedatetimeOptional
passwordExpirationTimedatetimeOptional
userStatusenumOptional
Active, Closed, Initiated, TemporaryLocked, UnconfirmedEmail
Allowed values:
userIdlongOptional
namestringOptional<=64 characters
hasLivebooleanOptional
ownsUnarchivedLivebooleanOptional
hasApprovedTradingPermissionbooleanOptional
hasSimPlusbooleanOptional
showKIDsbooleanOptional