Skip to content
Sursa Developers

POST/oauth/token

Issue an OAuth 2.0 token

oauth_token

The OAuth 2.0 token endpoint (RFC 6749, section 3.2). grant_type: authorization_code exchanges a one-time code for a token pair and requires code_verifier (PKCE S256); refresh_token issues a new pair for a refresh token and invalidates the previous refresh token (rotation), and reusing an invalidated one revokes the whole chain; client_credentials issues a token on behalf of the organization, for a confidential app only, without a refresh token. A confidential client authenticates with the Authorization: Basic header or with the client_id and client_secret fields; a public client sends only client_id. An access token is valid for 1 hour, a refresh token for 90 days. Responses and errors follow RFC 6749, section 5, with Cache-Control: no-store. Added in 1.62.0.

Authentication

No credentials needed.

Request body

application/x-www-form-urlencoded

Object: OAuthTokenRequest

  • grant_typestringrequired

    Allowed values: authorization_coderefresh_tokenclient_credentials

  • codestring

    Authorization code (authorization_code).

  • redirect_uristring

    The same redirect URI as in the authorization request (authorization_code).

  • code_verifierstring

    The original PKCE value, 43 to 128 characters (authorization_code).

  • refresh_tokenstring

    Refresh (refresh_token).

  • scopestring

    Space-separated scopes, narrowing only (refresh_token, client_credentials).

  • client_idstring

    App ID, when the secret is not passed in the Authorization: Basic header.

  • client_secretstring

    Client secret of a confidential app, when it is not passed in the Authorization: Basic header.

Responses

200Tokens were issued.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: OAuthTokenResponse

  • access_tokenstringrequired

    Access token (kbat_…) for the Authorization: Bearer header.

  • token_typestringrequired

    Allowed values: Bearer

  • expires_inintegerrequired

    Lifetime of the access token in seconds.

  • refresh_tokenstring

    Refresh token (kbrt_…); absent for client credentials.

  • scopestringrequired

    Space-separated scopes of the token.

400Error as defined in RFC 6749, section 5.2.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: OAuthErrorResponse

401Invalid client credentials (`invalid_client`).

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: OAuthErrorResponse

Safe retries

Send an Idempotency-Key header (for example a UUID) with each POST and PATCH. A retry with the same key within 24 hours returns the saved response instead of running the request again.

Rate limits

Responses carry the RateLimit and RateLimit-Policy headers and the earlier X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 response has Retry-After in seconds: wait and retry.

← oauth · API reference