Token Exchange

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

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

POST

oauth2

token

Token Exchange

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

{
  "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:

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

Authorization Code Grant

Exchange an authorization code for access and refresh tokens.

Request Parameters

string

required

Must be authorization_code

string

required

The authorization code received from /oauth2/authorize

string

required

Your agent ID (obtained during registration)

string

required

Must exactly match the redirect_uri used in authorization request

string

required

The PKCE code verifier (OAuth 2.1 requirement)

string

Optional for public clients. Required for confidential clients.

Example Request

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

string

JWT access token for making authenticated API requests

string

Always Bearer

number

Token lifetime in seconds (typically 3600 = 1 hour)

string

Long-lived token for refreshing the access token

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

string

required

Must be refresh_token

string

required

The refresh token received from a previous token response

string

required

Your agent ID

string

Optional for public clients

Example Request

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

400

Missing or invalid required parameters

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

401

Invalid authorization code, expired code, or PKCE verification failed

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

401

Invalid client_id or client_secret

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

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 challengeSolutions:

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 minutesSolution: Restart the OAuth flow from /oauth2/authorize

redirect_uri does not match

Cause: Redirect URI doesn’t exactly match the one used in authorizationSolution: Ensure exact match including protocol, domain, port, and path

Invalid refresh token

Cause: Refresh token expired (30 days) or revokedSolution: 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

Authorization

Start the OAuth flow

User Info

Get user information with access token

API Documentation

OAuth Endpoints

Agent Endpoints

Token Exchange

Endpoint

Content Type

Grant Types

Authorization Code Grant

Request Parameters

Example Request

Success Response

Refresh Token Grant

Request Parameters

Example Request

Success Response

Error Responses

Common Issues

Token Lifetime

Security Notes

Authorization

User Info

​Endpoint

​Content Type

​Grant Types

​Authorization Code Grant

​Request Parameters

​Example Request

​Success Response

​Refresh Token Grant

​Request Parameters

​Example Request

​Success Response

​Error Responses

​Common Issues

​Token Lifetime

​Security Notes

​Related Endpoints

Authorization

User Info

Endpoint

Content Type

Grant Types

Authorization Code Grant

Request Parameters

Example Request

Success Response

Refresh Token Grant

Request Parameters

Example Request

Success Response

Error Responses

Common Issues

Token Lifetime

Security Notes

Related Endpoints