OAuth 2.1 token endpoint

POST

/oauth/token

curl --request POST \
  --url https://app.buildworkpro.com/api/v1/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data code=example \
  --data redirect_uri=example \
  --data client_id=example \
  --data client_secret=example \
  --data code_verifier=example \
  --data refresh_token=example \
  --data scope=example

• Production

Exchanges an authorization code (with PKCE verifier) or a refresh token for a new access token (and rotated refresh token). Body MUST be application/x-www-form-urlencoded per RFC 6749. Response carries Cache-Control: no-store. Confidential clients authenticate by passing client_secret in the body; public clients omit it. Refresh token reuse triggers family-wide revocation of all access + refresh tokens issued from the original grant.

Request Body

Media type application/x-www-form-urlencoded

object

grant_type

required

OAuth 2.1 grant type. Supported: authorization_code, refresh_token.

string

Example

authorization_code

code

Authorization code (required for grant_type=authorization_code).

string

redirect_uri

Must exact-match the redirect_uri originally used to obtain the code.

string

client_id

required

OAuth client identifier issued by the registration endpoint.

string

client_secret

Required for confidential clients; MUST be omitted for public clients.

string

code_verifier

PKCE verifier (S256). Required for grant_type=authorization_code.

string

refresh_token

Refresh token (required for grant_type=refresh_token).

string

scope

Optional space-separated scope list. For grant_type=refresh_token, MUST be a subset of the original refresh token’s scopes (scope downgrade only). Upgrade is rejected with invalid_scope.

string

Responses

200

Access token issued

Media type application/json

object

access_token

required

string

token_type

required

string

Allowed values: Bearer

expires_in

required

integer

refresh_token

string

scope

required

string

Example

{
  "token_type": "Bearer"
}

400

RFC 6749 §5.2 error envelope (invalid_request, invalid_grant, invalid_client, unsupported_grant_type)

Media type application/json

object

error

required

string

error_description

string

Example ^generated

{
  "error": "example",
  "error_description": "example"
}

401

Client authentication failed (invalid_client)

Media type application/json

object

error

required

string

error_description

string

Example ^generated

{
  "error": "example",
  "error_description": "example"
}