Skip to main content

Get an access token

POST 
/oauth/token

Exchange a client id and secret for a bearer token that lasts one hour.

Credentials may be sent three ways — pick whichever your HTTP client makes easiest. All three are equivalent:

  • a JSON body (shown below),
  • a form-encoded body, which is what most OAuth libraries send,
  • HTTP Basic, with the client id as the username. Basic wins if both are present, so a body parameter cannot downgrade a header.

Cache the token. One call an hour is the expected pattern; the token endpoint is rate limited to 20 requests per minute per IP, and ten consecutive failures against one client id lock it out for fifteen minutes.

Every credential failure — unknown client id, wrong secret, revoked credential, expired credential — answers the same 401 invalid_client. Telling you which one it was would tell an attacker which client ids exist.

Two things are checked before a token is issued: that the account's plan includes API access, and that the calling IP passes the account's IP allow-list if one is set. A blocked address answers 403 ip_not_allowed and gets no token at all.

The first time an account reaches this endpoint, the API Explorer achievement becomes collectable in the console. Nothing to do — it unlocks on its own.

Request​

Responses​

A one-hour bearer token.

Response Headers
    X-Request-Id

    Correlation id for this request. Quote it when reporting a problem.