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

# API Tokens

> Create API tokens for a simpler way to authenticate with the Privy API.

API tokens are a lightweight alternative to [OAuth applications](/docs/api-reference/authentication) for authenticating with the Privy API. Instead of exchanging client credentials for a short-lived OAuth access token, you generate a longer-lived token directly from the dashboard and use it immediately.

|                    | API Tokens                                  | OAuth Applications                                   |
| ------------------ | ------------------------------------------- | ---------------------------------------------------- |
| **Setup**          | Generate a token in the dashboard           | Create an app, then exchange credentials for a token |
| **Token lifetime** | 30 days to 1 year (or no expiry)            | 2 hours                                              |
| **Best for**       | Scripts, internal tools, quick integrations | Third-party integrations, automated token rotation   |

## Creating a token

<Steps>
  <Step title="Open API token settings">
    Navigate to **Settings > API Tokens** in your [Privy dashboard](https://dashboard.privy.com).
  </Step>

  <Step title="Create a new token">
    Click **Create Token**. Choose a descriptive name, select the scopes you need, and pick an expiration period.
  </Step>

  <Step title="Copy the token">
    The token is displayed **once** after creation. Copy it immediately and store it securely — you won't be able to view it again.
  </Step>
</Steps>

<Warning>
  Treat API tokens like passwords. Never share them in client-side code, public repositories, or URLs. If a token is compromised, revoke it immediately from the dashboard.
</Warning>

## Token format

API tokens use the prefix `privy_` followed by a 40-character hex string:

```
privy_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
```

## Scopes

Scopes control what your token can access. You select scopes when creating the token.

| Scope            | Description                                      |
| ---------------- | ------------------------------------------------ |
| `contacts_read`  | List and filter contacts                         |
| `contacts_write` | Create, update, unsubscribe, and delete contacts |
| `events_write`   | Ingest custom events                             |

## Using a token

Include the token in the `Authorization` header as a bearer token — exactly the same as an OAuth access token:

```bash theme={null}
curl -X GET "https://api.privy.com/v1/contacts" \
  -H "Authorization: Bearer privy_YOUR_TOKEN"
```

All API endpoints accept API tokens and OAuth access tokens in the same `Authorization` header format.

## Expiration

When creating a token, choose from the following lifetimes:

| Option        | Duration                               |
| ------------- | -------------------------------------- |
| 30 days       | Token expires 30 days after creation   |
| 60 days       | Token expires 60 days after creation   |
| 90 days       | Token expires 90 days after creation   |
| 1 year        | Token expires 1 year after creation    |
| No expiration | Token never expires (use with caution) |

Tokens that were created with an expiration can be **renewed** from the dashboard to extend them by their original duration.

## Revoking a token

You can revoke a token at any time from **Settings > API Tokens** in the dashboard. Revoked tokens are rejected immediately — any request using a revoked token receives a `401` error.

## Limits

Each Privy account can have up to **25 active API tokens** at a time. Revoked and expired tokens do not count toward this limit.

[Rate limits](/docs/api-reference/rate-limits) apply to API tokens the same way they apply to OAuth access tokens — all requests under the same account share the same rate limit budget.

## Error responses

| Status | Code                 | Cause                                                    |
| ------ | -------------------- | -------------------------------------------------------- |
| `401`  | `unauthorized`       | Token is missing, invalid, expired, or revoked           |
| `403`  | `insufficient_scope` | Token does not have the required scope for this endpoint |

See the [Errors](/docs/api-reference/errors) page for all error codes.