OAuth

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

Changed on

Implements the RFC 6749 §5.1/§5.2 token-endpoint body contract in * both directions: a successful exchange returns a flat JSON object with * access_token at the top level, and a failure returns a flat * {error, error_description} object — neither is wrapped in this API's * usual response envelope, since no standard OAuth client library (or MCP * connector) would find access_token or error inside a data key. * * The third grant, urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693), * is restricted to a confidential internal-service client (see /oauth/introspect) * and trades a front-end resource's access token (the subject_token) for one * minted for THIS API — the crossing an MCP server makes after a user consents, * since its own token can never be forwarded here directly. The issued token is * never wider than the subject: scope, when sent, must be a subset of the * subject's own scopes, and resource must equal this API's own resource * identifier exactly. No refresh token is issued; the caller re-exchanges from * the user's own token instead of holding unattended API access.

Copy as Markdown Open in ChatGPT Open in Claude

post/v1/oauth/token

Request

  • Base URL
    https://api.assinafy.com.br
  • URL
    https://api.assinafy.com.br/v1/oauth/token
  • Auth
    none required

Request body

grant_type'authorization_code' | 'refresh_token' | 'urn:ietf:params:oauth:grant-type:token-exchange' required

urn:ietf:params:oauth:grant-type:token-exchange is for internal service clients only (Assinafy's own MCP server) — an ordinary confidential or public client authenticates with it and always gets invalid_client, exactly as an unrecognized client would. Everyday integrators use authorization_code and refresh_token.

codestring
redirect_uristring uri
code_verifierstring

RFC 7636: 43-128 characters from [A-Za-z0-9-._~]. Shorter values are rejected with invalid_grant.

refresh_tokenstring
client_idstring required
client_secretstring

Confidential clients only. Public clients authenticate with PKCE and are never issued a secret; the token-exchange grant requires a confidential, internal-service client and therefore always requires this.

resourcestring uri

RFC 8707 resource indicator. For authorization_code/refresh_token, optional; when present it must be the resource value published by /.well-known/oauth-protected-resource and must match the one sent to /authorize, otherwise invalid_target. For the token-exchange grant it is REQUIRED and must equal this API's own resource identifier exactly (never a front-end resource such as the MCP server), otherwise invalid_target.

subject_tokenstring

Token-exchange grant only. The front-end resource's access token being traded in. Must be a live, original (never itself exchanged) token minted for a resource this server issues tokens for, other than this API's own audience.

subject_token_type'urn:ietf:params:oauth:token-type:access_token'

Token-exchange grant only. Required; only urn:ietf:params:oauth:token-type:access_token is supported.

requested_token_type'urn:ietf:params:oauth:token-type:access_token'

Token-exchange grant only. Optional; when present it must agree with the only type this server issues.

Response

The token response

access_tokenstring
issued_token_typestring

Present only for the token-exchange grant, per RFC 8693 §2.2.1.

token_typestring
expires_ininteger

For the token-exchange grant, clamped to the subject token's own remaining lifetime as well as the exchanged-token TTL — never longer than either.

refresh_tokenstring nullable

Present only when the offline_access scope was requested AND consented on the authorization_code/refresh_token grants. Never present for the token-exchange grant. Without it a client must send the user through the authorization flow again once the access token expires.

scopestring

The scope of the ACCESS token. offline_access is a request-time signal rather than a permission, so it never appears here even when it was requested.

id_tokenstring nullable

A signed OIDC id_token (RS256). Present only when the openid scope was granted.

Example response

{
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "documents:read"
}

Changes