> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate with the Upsun Cloud REST API using OAuth2 API tokens.

The Upsun Cloud REST API uses OAuth2 bearer tokens for authentication. You exchange an API token for a short-lived access token, then include it in the `Authorization` header of every request.

## Create an API token

You will first need to have an [Upsun account](https://auth.upsun.com/register/) and [create an API Token](https://developer.upsun.com/cli/api-tokens.md) via the Console.

## Exchange for an access token

Use the token exchange endpoint to get a short-lived access token:

```bash theme={null}
curl -u platform-api-user: \
  -d 'grant_type=api_token&api_token=YOUR_API_TOKEN' \
  https://auth.upsun.com/oauth2/token
```

The response contains a bearer token valid for **900 seconds** (15 minutes):

```json theme={null}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "expires_in": 900,
  "token_type": "bearer"
}
```

## Make authenticated requests

Include the access token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.upsun.com/projects
```

> [!NOTE]
>
> **Base URL:** All API requests go to `https://api.upsun.com`.

## Token lifecycle

| Property | Value |
| - | - |
| Token type | Bearer |
| Expires in | 900 seconds (15 minutes) |
| Exchange endpoint | `https://auth.upsun.com/oauth2/token` |
| Grant type | `api_token` |

Access tokens expire after 15 minutes. Your application should handle re-authentication by exchanging the API token again when a request returns `401 Unauthorized`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.