Skip to content
go-api-boilerplate

The token endpoint (RFC 6749 §3.2).

POST
/oauth/token
curl --request POST \
  --url https://example.com/api/auth/oauth/token \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data code=example \
  --data redirect_uri=example \
  --data code_verifier=example \
  --data refresh_token=example \
  --data scope=example \
  --data client_id=example \
  --data client_secret=example

Grants: authorization_code (with the code_verifier and the same redirect_uri), client_credentials and refresh_token. Refresh tokens rotate: presenting one that was rotated already revokes the grant. The client authenticates with HTTP Basic (client_secret_basic) or with client_id and client_secret in the body (client_secret_post), not both. Limited per client IP.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/x-www-form-urlencoded
object
grant_type
required
string
Allowed values: authorization_code client_credentials refresh_token
code
string
redirect_uri
string
code_verifier
string
>= 43 characters <= 128 characters
refresh_token
string
scope
string
client_id
string
client_secret
string

Responses

Section titled “Responses”

200

Section titled “200”

Tokens.

Media typeapplication/json
object
access_token
required
string
token_type
required
string
Allowed value: Bearer
expires_in
required
integer
refresh_token

Not for client_credentials.

string
scope
required
string

Example 

{
  "token_type": "Bearer"
}

Headers

Section titled “Headers”
Cache-Control
string
Allowed value: no-store

400

Section titled “400”

The request was refused (RFC 6749 §5.2).

Media typeapplication/json

An RFC 6749 §5.2 error response.

object
error
required
string
Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope
error_description
string

Example 

{
  "error": "invalid_request"
}

Headers

Section titled “Headers”
Cache-Control
string
Allowed value: no-store

401

Section titled “401”

Client authentication failed, error invalid_client.

Media typeapplication/json

An RFC 6749 §5.2 error response.

object
error
required
string
Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope
error_description
string

Example 

{
  "error": "invalid_request"
}

Headers

Section titled “Headers”
WWW-Authenticate
string
Cache-Control
string
Allowed value: no-store

413

Section titled “413”

The body is larger than 64 KiB.

Media typeapplication/problem+json

An RFC 9457 problem.

object
type
required
string
title
required
string
status
required
integer
detail
string
instance
string
request_id
string
errors
object
key
additional properties
string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": {
    "additionalProperty": "example"
  }
}

429

Section titled “429”

This client IP is sending too many requests.

Media typeapplication/problem+json

An RFC 9457 problem.

object
type
required
string
title
required
string
status
required
integer
detail
string
instance
string
request_id
string
errors
object
key
additional properties
string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": {
    "additionalProperty": "example"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait.

500

Section titled “500”

The service failed; the problem says nothing more.

Media typeapplication/problem+json

An RFC 9457 problem.

object
type
required
string
title
required
string
status
required
integer
detail
string
instance
string
request_id
string
errors
object
key
additional properties
string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": {
    "additionalProperty": "example"
  }
}