Skip to content
InternetData

Token

post/oauth/token

Issues tokens for three grant types: a device code, an authorization code and a refresh token.

urn:ietf:params:oauth:grant-type:device_code polls a device authorization. Until the person approves it answers authorization_pending; poll faster than interval and it answers slow_down, which means widen your interval and keep it widened.

authorization_code exchanges a code from /oauth/authorize, with the code_verifier matching the challenge you sent and the same redirect_uri. A code works once: presenting it again also revokes what the first exchange issued.

refresh_token exchanges a refresh token. The presented token is consumed whatever happens next, so store the new one before using it. Presenting a consumed refresh token again ends the whole authorization, since it means the token was copied.

Request body

application/x-www-form-urlencoded

grant_typerequiredstring

urn:ietf:params:oauth:grant-type:device_code, authorization_code or refresh_token.

client_idrequiredstring
device_codestring

Required by the device code grant.

codestring

Required by the authorization code grant.

code_verifierstring

Required by the authorization code grant.

redirect_uristring

Required by the authorization code grant: the redirect_uri the code was issued against, exactly.

resourcestring

Authorization code grant, optional: RFC 8707, and it must name what was authorized.

refresh_tokenstring

Required by the refresh token grant.

Responses

200application/json

Tokens.

access_tokenrequiredstring
token_typerequiredstring

Always Bearer.

expires_inrequiredinteger

Seconds until the access token expires.

refresh_tokenstring

Always returned. A refresh consumes the token it presents, so keep this one.

scopestring

What was actually granted, which may be narrower than what was asked for.

mslm:apikey_idstring

Not part of OAuth, and only for our own clients. The ID of the API key the person picked when they approved, returned by every grant while this authorization may still read that key back. Absent when no key was picked, or when the person's role no longer allows reading keys back.

mslm:apikeystring

Not part of OAuth, and only for our own clients: a client that signed in with a Client ID Metadata Document or registered itself never receives a key. The API key itself, so a device ends up holding an ordinary key. Returned by the device code and authorization code grants only, never by a refresh, and only alongside mslm:apikey_id. Absent when that key's secret cannot be read back, which is the case for a key created before keys could be shown again in the console; a rotated key can be.

TypeScript type
ts
{
  access_token: string;
  token_type: string;
  expires_in: number;
  refresh_token?: string;
  scope?: string;
  "mslm:apikey_id"?: string;
  "mslm:apikey"?: string;
}
400application/json

An RFC 6749 error. authorization_pending and slow_down are normal answers while polling a device authorization, not failures. access_denied means the person refused, and expired_token that the device code is no longer valid: it expired, or it was already exchanged or refused. invalid_grant means the code, device code or refresh token is not valid for this client_id. invalid_target means resource names something other than what was authorized. slow_down also answers any grant when this address sends too many requests.

errorrequiredstring
error_descriptionstring
TypeScript type
ts
{
  error: string;
  error_description?: string;
}
401application/json

invalid_client: the client_id is not registered.

errorrequiredstring
error_descriptionstring
TypeScript type
ts
{
  error: string;
  error_description?: string;
}