Authorization & tokens
Get or refresh a token
Exchange an authorization code, rotate a refresh token, or issue a service token using client credentials.
/oauth/token- Authentication
- OAuth protocol client authentication
- Required scopes
- See authentication requirements
- Idempotency key
- Not required
How to use this endpoint
Each access token is restricted to its selected resource. Confidential Filing API clients use their registered authentication method. Public MCP clients send client_id without a secret, use the exact MCP resource and cannot use client_credentials.
curl --request POST '<origin from OAuth metadata>/oauth/token' \
--user '<client_id>:<client_secret>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=<approved scopes>'Use the exact endpoint URL from your environment's metadata. Confidential client examples use client_secret_basic; public MCP clients use client_id without a secret.
Request fields
10 fieldsgrant_typeSee descriptionSee description
authorization_code | refresh_token | client_credentials
codeSee descriptionSee description
required only for authorization_code
redirect_uriSee descriptionSee description
required exact URI only for authorization_code
code_verifierSee descriptionSee description
required PKCE verifier only for authorization_code
refresh_tokenSee descriptionSee description
required only for refresh_token
scopeSee descriptionSee description
optional space-delimited subset; offline_access is forbidden for client_credentials
client_idSee descriptionSee description
required where the selected client-auth method needs it
client_assertion_typeSee descriptionSee description
JWT bearer assertion type for private_key_jwt
client_assertionSee descriptionSee description
short-lived signed assertion for private_key_jwt
resourceSee descriptionSee description
Optional for the default Filing API resource; required for MCP. Use the exact resource from discovery and keep the resource selected for the authorization code or refresh token.
Headers (3)
AuthorizationConditional / optional- Use HTTP Basic for client_secret_basic. For private_key_jwt, omit this header and send the registered assertion fields. Public MCP clients use client_id with no Basic header, client secret or assertion. The example builder defaults to a confidential client; remove --user when adapting it for a public client.
Content-TypeRequired- application/x-www-form-urlencoded
DPoPConditional / optional- RFC 9449 proof; mandatory when configured and bound on refresh-token rotation.
curl --request POST '<origin from OAuth metadata>/oauth/token' \
--user '<client_id>:<client_secret>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=<approved scopes>'Use the exact endpoint URL from your environment's metadata. Confidential client examples use client_secret_basic; public MCP clients use client_id without a secret.
Successful outcomes: ok.
{
"access_token": "<short_lived_rs256_jwt>",
"token_type": "Bearer",
"expires_in": 600,
"refresh_token": "<rotating_opaque_token_when_granted>",
"scope": "filers.read recipients.read"
}token issued
Errors to handle
Use the returned status and code to decide what to correct or retry.
- 400
invalid_request | invalid_grant | invalid_scope | unsupported_grant_type | invalid_dpop_proof - 401
invalid_client - 503
temporarily_unavailable