---
title: "Exchange authorization code or refresh token"
method: POST
path: "/v1/oauth2/token"
tags: ["Authentication"]
---

# Exchange authorization code or refresh token

`POST /v1/oauth2/token`

## Request

- Base URL: `https://auth.foundation.dev.trusspayments.com`
- URL: `https://auth.foundation.dev.trusspayments.com/v1/oauth2/token`
- Auth: none required

Exchange an authorization code for access and refresh tokens, or use a refresh token to obtain a new access token.

This endpoint supports two grant types:

- **`authorization_code`** — Exchange the authorization code received from the OAuth callback for access and refresh tokens.
- **`refresh_token`** — Use a valid refresh token to obtain a new access token without requiring re-authorization.

Access tokens expire after 60 minutes. Use the `refresh_token` grant type to obtain a new access token before expiry.

## Request body `application/x-www-form-urlencoded`

- union
  - AuthorizationCodeTokenRequest: Request body for exchanging an authorization code for tokens
    - `grant_type` 'authorization_code', required: Must be `authorization_code`
    - `code` string, required: The authorization code received from the OAuth callback
    - `redirect_uri` string, uri, required: Must match the redirect_uri used in the authorization request
    - `client_id` string, required: Your application's client ID
    - `client_secret` string, required: Your application's client secret
  - RefreshTokenRequest: Request body for refreshing an access token
    - `grant_type` 'refresh_token', required: Must be `refresh_token`
    - `refresh_token` string, required: The refresh token obtained from a previous token exchange
    - `client_id` string, required: Your application's client ID
    - `client_secret` string, required: Your application's client secret

## Response `200`

Token exchange successful

- TokenResponse
  - `access_token` string, required: JWT access token to include in API request Authorization headers
  - `refresh_token` string: Token used to obtain a new access token when the current one expires
  - `token_type` 'bearer', required
  - `expires_in` integer, required: Token lifetime in seconds (typically 3600)
  - `scope` string: Space-separated list of granted scopes

## Other responses

- `400`: Invalid request (e.g. invalid grant type, expired code, invalid refresh token)
- `401`: Invalid client credentials

---

[API](https://skmtc.dev/trusspayments/apis/truss-api.md) - [All operations](https://skmtc.dev/trusspayments/apis/truss-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trusspayments/apis/truss-api/revisions/370e29ce37ac?raw)