> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.upwardli.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.upwardli.com/_mcp/server.

# Token Exchange

This page describes how to request a token exchange. These authentication tokens should be used when making api requests for a single user.

## Scopes

| Scope                           | Use                                                                                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `api:read`                      | Used to perform read-only operations for machine to machine (M2M) scenrarios.                                          |
| `api:write`                     | Used to perform full CRUD operations for machine to machine (M2M) scenrarios.                                          |
| `ui:client-onboarding`          | Used for the [Onboarding Client Component](/ui-components/onboarding)                                                  |
| `api:credit-insights:read`      | Access to Read [Credit Insights](/api-access/api-reference/credit-insights/retrieve-credit-insights-overview-v-2) data |
| `api:profile:read`              | Access to Read [Profile](/api-access/api-reference/consumers/retrieve-consumer) data                                   |
| `api:trade-line:read`           | Access to Read [Credit Line](/api-access/api-reference/credit-lines/retrieve-get-credit-line) data                     |
| `consumer:<upward_consumer_id>` | Access to Read and Write data for a specific consumer                                                                  |

## Exchanging Tokens Using The API

Once a valid token has been obtained using the [Authentication API](/concepts/authentication), a limited scope token can be obtained using the token exchange API. This token can be used to make requests for a specific consumer, and is safe to send to the client application/web browser as needed.

To request a token exchange send a POST to our auth server containing the access\_token and requested scope.

## Token Exchange Request

POST [https://auth-sandbox.upwardli.com/auth/token/exchange/](https://auth-sandbox.upwardli.com/auth/token/exchange/)

```json
Header
{
    "Authorization":"Bearer [access_token]"
}
Body
{
    "grant_type":"urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token_type":"urn:ietf:params:oauth:token-type:access_token",
    "subject_token":"[access_token]",
    "audience":"https://auth-sandbox.upwardli.com",
    "scope":"api:credit-insights:read api:profile:read api:write consumer:[upward_consumer_id]"
}
```

### Here's what a successful response looks like:

```json
{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "[scoped access token]",
    "scope": "api:credit-insights:read api:profile:read api:write",
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
```

Notes:

* The audience must be for the correct [Environment](/api-access/environments-and-base-ur-ls).
* The upward\_consumer\_id is the Upward id that you get from the [Consumer.created](/concepts/webhooks/event-catalog#consumer-webhooks) webhook.
* The new access token is a significantly longer string than the original access token.