Skip to content
GitmoapAPIBeta
Identity & platformoauth
POST/oauth/token

Exchange an authorization code, or a refresh token, for an access token

oauth_token
  • Public
    This operation declares no security requirement: it takes no token.
  • Audited · mutation

    x-gitmoap-audit: {"kind":"audited","arg":"mutation"}

  • Quota · oauth grants per user

    x-gitmoap-quota: {"kind":"enforced","arg":"oauth_grants_per_user"}

The OAuth 2.1 token endpoint. It takes no sign-in: the request is authenticated by what it carries — an authorization code with the client id, redirect and PKCE verifier it was issued for, or a refresh token. The access token is an ordinary short-lived personal access token limited to what the person allowed, and a refresh renews it with a new refresh token, never with more access. A code allows one attempt within a minute; a code used twice, or a refresh token presented after it was replaced, revokes the connection.

Request body

application/x-www-form-urlencoded
  • grant_typestringauthorization_code or refresh_token.
  • client_idstring or nulloptional
  • codestring or nulloptional
  • code_verifierstring or nulloptional
  • redirect_uristring or nulloptional
  • refresh_tokenstring or nulloptional
  • resourcestring or nulloptionalThe protected resource the token is for.
  • scopestring or nulloptionalSpace-separated scopes; on refresh, at most the grant's own.
Request body exampleSynthesized example
{
"grant_type": "grant-type-35dd"
}

Responses

200An access token and the refresh token that renews itapplication/json
  • access_tokenstring
  • expires_ininteger · int640–∞Seconds until the access token expires.
  • refresh_tokenstring
  • scopestringThe scopes the access token carries, space-separated.
  • token_typestringAlways Bearer.
200 exampleSynthesized example
{
"access_token": "access-token-52dd",
"expires_in": 15,
"refresh_token": "refresh-token-b23d",
"scope": "scope-5e63",
"token_type": "token-type-1c39"
}
400The code or refresh token was refused, or the request was malformedapplication/json
Error codes
  • BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type
  • errorstringinvalid_request, invalid_client, invalid_grant, invalid_scope, invalid_target, unsupported_grant_type or server_error.
  • error_descriptionstring or nulloptional
400 exampleSynthesized example
{
"error": "error-13f1"
}
429The person has connected as many apps as they mayapplication/json
Error codes
  • TOO_MANY_REQUESTSRetryableA quota, a rate limit or a transfer budget is spent. When the response carries Retry-After, retry after that many seconds
  • errorstringinvalid_request, invalid_client, invalid_grant, invalid_scope, invalid_target, unsupported_grant_type or server_error.
  • error_descriptionstring or nulloptional
429 exampleSynthesized example
{
"error": "error-e7b0"
}
501The authorization server is not configured on this deploymentapplication/json
Error codes
  • NOT_IMPLEMENTEDThis deployment has not configured the feature the operation needs; the message names it
  • errorstringinvalid_request, invalid_client, invalid_grant, invalid_scope, invalid_target, unsupported_grant_type or server_error.
  • error_descriptionstring or nulloptional
501 exampleSynthesized example
{
"error": "error-0e16"
}

CLI

gitmoap oauth oauth-token

  • --bodyfileoptional