Skip to main content

​
Endpoint

POST /oauth/token For token-based authentication, use the oauth/token endpoint to get an access token for your application to make authenticated calls to a secure API. Optionally, you can also retrieve an ID Token and a Refresh Token. ID Tokens contain user information in the form of scopes you application can extract to provide a better user experience. Refresh Tokens allow your application to request a new access token once the current token expires without interruping the user experience. To learn more, read ID Tokens and Refresh Tokens. Note that the only OAuth 2.0 flows that can retrieve a Refresh Token are: This is the flow that regular web apps use to access an API. Use this endpoint to exchange an Authorization Code for a token.

​
Headers

​
string
A DPoP proof for the request. This is optional and only required if your application uses Demonstrating Proof-of-Possession.

​
Body Parameters

The request body is in application/x-www-form-urlencoded format.
​
string
required
Denotes the flow you are using. For Authorization Code, use authorization_code.
​
string
required
Your application’s Client ID.
​
string
required
Your application’s Client Secret.
​
string
required
The Authorization Code received from the initial /authorize call.
​
string
This is required only if it was set at the GET /authorize endpoint. The values from /authorize must match the value you set at /oauth/token.

​
Response Schema

​
Agent access tokens

Agents as principals is an Early Access feature.
When the application exchanging the code is linked to an agent and agent subject claims are enabled for the target API, the issued access token records the agent as the actor on the user’s behalf:
  • The sub claim remains the user identifier. The agent identity surfaces in the act claim, not in sub.
  • The act claim identifies the agent: { "sub": "agt_72jbvv7LfRKYp59gtRLtkn", "sub_profile": "ai_agent", "client_id": "YOUR_CLIENT_ID", "iss": "https://YOUR_DOMAIN/" }.
  • The token includes sub_profile: "user" and client_profile with an ai_agent suffix, for example web_app ai_agent.
If the access token already carries an actor from a session transfer or an On-Behalf-Of exchange, that actor takes precedence and no agent actor is added. These claims apply to the access token only; the ID token is unaffected. The response shape is unchanged. To learn more, read Access Token Profiles.

​
Response Messages