Token Exchange

Exchange authorization code for tokens or refresh an access token

POST /oauth2/token

Token Exchange

cURL

curl --request POST \
  --url https://api.example.com/oauth2/token \
  --header 'Content-Type: application/json' \
  --data '
{
  "grant_type": "<string>",
  "code": "<string>",
  "client_id": "<string>",
  "redirect_uri": "<string>",
  "code_verifier": "<string>",
  "client_secret": "<string>",
  "refresh_token": "<string>"
}
'

import requests

url = "https://api.example.com/oauth2/token"

payload = {
    "grant_type": "<string>",
    "code": "<string>",
    "client_id": "<string>",
    "redirect_uri": "<string>",
    "code_verifier": "<string>",
    "client_secret": "<string>",
    "refresh_token": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    grant_type: '<string>',
    code: '<string>',
    client_id: '<string>',
    redirect_uri: '<string>',
    code_verifier: '<string>',
    client_secret: '<string>',
    refresh_token: '<string>'
  })
};

fetch('https://api.example.com/oauth2/token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/oauth2/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'grant_type' => '<string>',
    'code' => '<string>',
    'client_id' => '<string>',
    'redirect_uri' => '<string>',
    'code_verifier' => '<string>',
    'client_secret' => '<string>',
    'refresh_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/oauth2/token"

	payload := strings.NewReader("{\n  \"grant_type\": \"<string>\",\n  \"code\": \"<string>\",\n  \"client_id\": \"<string>\",\n  \"redirect_uri\": \"<string>\",\n  \"code_verifier\": \"<string>\",\n  \"client_secret\": \"<string>\",\n  \"refresh_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/oauth2/token")
  .header("Content-Type", "application/json")
  .body("{\n  \"grant_type\": \"<string>\",\n  \"code\": \"<string>\",\n  \"client_id\": \"<string>\",\n  \"redirect_uri\": \"<string>\",\n  \"code_verifier\": \"<string>\",\n  \"client_secret\": \"<string>\",\n  \"refresh_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/oauth2/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"grant_type\": \"<string>\",\n  \"code\": \"<string>\",\n  \"client_id\": \"<string>\",\n  \"redirect_uri\": \"<string>\",\n  \"code_verifier\": \"<string>\",\n  \"client_secret\": \"<string>\",\n  \"refresh_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

200

{
  "access_token": "<string>",
  "token_type": "<string>",
  "expires_in": 123,
  "refresh_token": "<string>",
  "scope": "<string>",
  "invalid_request": {},
  "invalid_grant": {},
  "invalid_client": {},
  "unsupported_grant_type": {}
}

Endpoint

POST /oauth2/token

Content Type

application/x-www-form-urlencoded

Grant Types

This endpoint supports two grant types:

1. authorization_code - Exchange authorization code for tokens
2. refresh_token - Refresh an expired access token

---

Authorization Code Grant

Exchange an authorization code for access and refresh tokens.

Request Parameters

grant_type · string · required

Must be authorization_code

code · string · required

The authorization code received from /oauth2/authorize

client_id · string · required

Your agent ID (obtained during registration)

redirect_uri · string · required

Must exactly match the redirect_uri used in authorization request

code_verifier · string · required

The PKCE code verifier (OAuth 2.1 requirement)

client_secret · string

Optional for public clients. Required for confidential clients.

Example Request

cURL

curl -X POST https://api.auth-agent.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_HERE" \
  -d "client_id=your_agent_id" \
  -d "redirect_uri=http://localhost:3000/callback" \
  -d "code_verifier=PKCE_VERIFIER_HERE"

const response = await fetch("https://api.auth-agent.com/oauth2/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code: "AUTH_CODE_HERE",
    client_id: "your_agent_id",
    redirect_uri: "http://localhost:3000/callback",
    code_verifier: "PKCE_VERIFIER_HERE",
  }),
});

const tokens = await response.json();

import requests

response = requests.post(
    'https://api.auth-agent.com/oauth2/token',
    data={
        'grant_type': 'authorization_code',
        'code': 'AUTH_CODE_HERE',
        'client_id': 'your_agent_id',
        'redirect_uri': 'http://localhost:3000/callback',
        'code_verifier': 'PKCE_VERIFIER_HERE',
    }
)

tokens = response.json()

Success Response

access_token · string

JWT access token for making authenticated API requests

token_type · string

Always Bearer

expires_in · number

Token lifetime in seconds (typically 3600 = 1 hour)

refresh_token · string

Long-lived token for refreshing the access token

scope · string

Space-separated list of granted scopes

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}

---

Refresh Token Grant

Refresh an expired access token using a refresh token.

Request Parameters

grant_type · string · required

Must be refresh_token

refresh_token · string · required

The refresh token received from a previous token response

client_id · string · required

Your agent ID

client_secret · string

Optional for public clients

Example Request

cURL

curl -X POST https://api.auth-agent.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN_HERE" \
  -d "client_id=your_agent_id"

const response = await fetch("https://api.auth-agent.com/oauth2/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    grant_type: "refresh_token",
    refresh_token: "REFRESH_TOKEN_HERE",
    client_id: "your_agent_id",
  }),
});

const tokens = await response.json();

import requests

response = requests.post(
    'https://api.auth-agent.com/oauth2/token',
    data={
        'grant_type': 'refresh_token',
        'refresh_token': 'REFRESH_TOKEN_HERE',
        'client_id': 'your_agent_id',
    }
)

tokens = response.json()

Success Response

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

Refresh tokens are not rotated by default. The same refresh token can be used multiple times.

---

Error Responses

invalid_request · 400

Missing or invalid required parameters

{
  "error": "invalid_request",
  "error_description": "Missing required parameters: code, client_id, redirect_uri"
}

invalid_grant · 401

Invalid authorization code, expired code, or PKCE verification failed

{
  "error": "invalid_grant",
  "error_description": "PKCE verification failed"
}

invalid_client · 401

Invalid client_id or client_secret

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

unsupported_grant_type · 400

Grant type not supported (OAuth 2.1 only supports authorization_code and refresh_token)

{
  "error": "unsupported_grant_type",
  "error_description": "Only authorization_code and refresh_token grant types are supported"
}

Common Issues

PKCE verification failed

Cause: Code verifier doesn’t match the original code challenge

Solutions:

• Ensure you’re using the same verifier that generated the challenge
• Check that the verifier is stored correctly in sessionStorage
• Verify the SHA-256 hashing is implemented correctly

Authorization code has expired

Cause: Code older than 10 minutes

Solution: Restart the OAuth flow from /oauth2/authorize

redirect_uri does not match

Cause: Redirect URI doesn’t exactly match the one used in authorization

Solution: Ensure exact match including protocol, domain, port, and path

Invalid refresh token

Cause: Refresh token expired (30 days) or revoked

Solution: User must re-authenticate via /oauth2/authorize

Token Lifetime

Token Type	Lifetime	Notes
Authorization Code	10 minutes	Single use only
Access Token	1 hour	Can be refreshed
Refresh Token	30 days	Long-lived

Security Notes

• Authorization codes are single-use and expire quickly - Always use PKCE (required by OAuth 2.1) - Store refresh tokens securely - Never expose tokens in URLs or logs

Related Endpoints

Authorization

Start the OAuth flow

User Info

Get user information with access token