Exchange Authorization Code

Exchange authorization code for access token

curl --request POST \
  --url https://api.example.com/oauth/token/exchange \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "code_abc123...",
  "clientId": "app_abc123...",
  "clientSecret": "cs_abc123...",
  "redirectUri": "https://example.com/oauth/callback",
  "grantType": "authorization_code",
  "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}
'

import requests

url = "https://api.example.com/oauth/token/exchange"

payload = {
    "code": "code_abc123...",
    "clientId": "app_abc123...",
    "clientSecret": "cs_abc123...",
    "redirectUri": "https://example.com/oauth/callback",
    "grantType": "authorization_code",
    "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}
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({
    code: 'code_abc123...',
    clientId: 'app_abc123...',
    clientSecret: 'cs_abc123...',
    redirectUri: 'https://example.com/oauth/callback',
    grantType: 'authorization_code',
    codeVerifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
  })
};

fetch('https://api.example.com/oauth/token/exchange', 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/oauth/token/exchange",
  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([
    'code' => 'code_abc123...',
    'clientId' => 'app_abc123...',
    'clientSecret' => 'cs_abc123...',
    'redirectUri' => 'https://example.com/oauth/callback',
    'grantType' => 'authorization_code',
    'codeVerifier' => 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
  ]),
  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/oauth/token/exchange"

	payload := strings.NewReader("{\n  \"code\": \"code_abc123...\",\n  \"clientId\": \"app_abc123...\",\n  \"clientSecret\": \"cs_abc123...\",\n  \"redirectUri\": \"https://example.com/oauth/callback\",\n  \"grantType\": \"authorization_code\",\n  \"codeVerifier\": \"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"\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/oauth/token/exchange")
  .header("Content-Type", "application/json")
  .body("{\n  \"code\": \"code_abc123...\",\n  \"clientId\": \"app_abc123...\",\n  \"clientSecret\": \"cs_abc123...\",\n  \"redirectUri\": \"https://example.com/oauth/callback\",\n  \"grantType\": \"authorization_code\",\n  \"codeVerifier\": \"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"code\": \"code_abc123...\",\n  \"clientId\": \"app_abc123...\",\n  \"clientSecret\": \"cs_abc123...\",\n  \"redirectUri\": \"https://example.com/oauth/callback\",\n  \"grantType\": \"authorization_code\",\n  \"codeVerifier\": \"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"\n}"

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

POST

oauth

token

exchange

Exchange authorization code for access token

curl --request POST \
  --url https://api.example.com/oauth/token/exchange \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "code_abc123...",
  "clientId": "app_abc123...",
  "clientSecret": "cs_abc123...",
  "redirectUri": "https://example.com/oauth/callback",
  "grantType": "authorization_code",
  "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}
'

import requests

url = "https://api.example.com/oauth/token/exchange"

payload = {
    "code": "code_abc123...",
    "clientId": "app_abc123...",
    "clientSecret": "cs_abc123...",
    "redirectUri": "https://example.com/oauth/callback",
    "grantType": "authorization_code",
    "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}
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({
    code: 'code_abc123...',
    clientId: 'app_abc123...',
    clientSecret: 'cs_abc123...',
    redirectUri: 'https://example.com/oauth/callback',
    grantType: 'authorization_code',
    codeVerifier: 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
  })
};

fetch('https://api.example.com/oauth/token/exchange', 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/oauth/token/exchange",
  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([
    'code' => 'code_abc123...',
    'clientId' => 'app_abc123...',
    'clientSecret' => 'cs_abc123...',
    'redirectUri' => 'https://example.com/oauth/callback',
    'grantType' => 'authorization_code',
    'codeVerifier' => 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
  ]),
  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/oauth/token/exchange"

	payload := strings.NewReader("{\n  \"code\": \"code_abc123...\",\n  \"clientId\": \"app_abc123...\",\n  \"clientSecret\": \"cs_abc123...\",\n  \"redirectUri\": \"https://example.com/oauth/callback\",\n  \"grantType\": \"authorization_code\",\n  \"codeVerifier\": \"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"\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/oauth/token/exchange")
  .header("Content-Type", "application/json")
  .body("{\n  \"code\": \"code_abc123...\",\n  \"clientId\": \"app_abc123...\",\n  \"clientSecret\": \"cs_abc123...\",\n  \"redirectUri\": \"https://example.com/oauth/callback\",\n  \"grantType\": \"authorization_code\",\n  \"codeVerifier\": \"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"code\": \"code_abc123...\",\n  \"clientId\": \"app_abc123...\",\n  \"clientSecret\": \"cs_abc123...\",\n  \"redirectUri\": \"https://example.com/oauth/callback\",\n  \"grantType\": \"authorization_code\",\n  \"codeVerifier\": \"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\"\n}"

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

Exchanges an authorization code for access and refresh tokens (Authorization Code Flow).

This is a PUBLIC ENDPOINT (no authentication required). Rate-limited to 15 requests per minute.

Request Body

Field	Type	Required	Description
`code`	string	Yes	Authorization code from `/oauth/authorize`
`clientId`	string	Yes	OAuth application client ID
`clientSecret`	string	Yes	OAuth application client secret
`redirectUri`	string	Yes	Redirect URI (must match authorization request)
`grantType`	string	Yes	Grant type (default: “authorization_code”)

Example Request

curl -X POST https://api.timbrix.mx/oauth/token/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "code": "code_abc123xyz...",
    "clientId": "app_1234567890abcdef",
    "clientSecret": "cs_1234567890abcdef",
    "redirectUri": "https://example.com/oauth/callback",
    "grantType": "authorization_code"
  }'

import { Timbrix } from "@timbrix/sdk"

const client = new Timbrix()

const tokens = await client.oauth.exchangeCode({
  code: "code_abc123xyz...",
  clientId: "app_1234567890abcdef",
  clientSecret: "cs_1234567890abcdef",
  redirectUri: "https://example.com/oauth/callback",
})
console.log(tokens.access_token, tokens.refresh_token)

Example Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "rt_abc123xyz...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:user read:organization"
}

Important Notes

The redirectUri must exactly match the one used in the authorization request
Authorization codes are single-use and expire quickly
Store the refresh token securely for token renewal

Common Errors

400 Bad Request

Invalid request. Check required fields: code, client_id, client_secret, redirect_uri, grant_type.

401 Unauthorized

Invalid authorization code, client credentials, or redirect URI mismatch.

429 Too Many Requests

Rate limit exceeded. Maximum 15 requests per minute for code exchange.

Body

application/json

code

string

required

Authorization code received from the authorization endpoint

Example:

"code_abc123..."

clientId

string

required

OAuth application client ID

Example:

"app_abc123..."

clientSecret

string

required

OAuth application client secret

Example:

"cs_abc123..."

redirectUri

string

required

Redirect URI that was used in the authorization request (must match exactly)

Example:

"https://example.com/oauth/callback"

grantType

string

default:authorization_code

required

Grant type (authorization_code for code exchange)

Example:

"authorization_code"

codeVerifier

string

PKCE code verifier (required if code_challenge was provided during authorization). Random string used to generate the code_challenge.

Example:

"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

Response

Code exchanged successfully. Returns access_token, refresh_token, token_type (Bearer), expiration time, and scopes.

API documentation

Organizations

Members

Invites

Auth

OAuth

Customers

SAT Catalogs

Invoices

Products

Users

Webhooks

API Keys

organizations

users

api-keys

oauth

monitoring

auth

customers

products

sat

webhooks

invoices

partners

partners-admin

Exchange Authorization Code

Request Body

Example Request

Example Response

Important Notes

Common Errors

400 Bad Request

401 Unauthorized

429 Too Many Requests

Body

Response

​Request Body

​Example Request

​Example Response

​Important Notes

​Common Errors

​400 Bad Request

​401 Unauthorized

​429 Too Many Requests

Body

Response

Request Body

Example Request

Example Response

Important Notes

Common Errors

400 Bad Request

401 Unauthorized

429 Too Many Requests