API Tokens

API tokens are a lightweight alternative to OAuth applications 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

Open API token settings

Navigate to Settings > API Tokens in your Privy dashboard.

Create a new token

Click Create Token. Choose a descriptive name, select the scopes you need, and pick an expiration period.

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.

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.

If you use subaccounts, each eligible subaccount can create its own tokens under Settings > API Tokens. A token created in a subaccount can only access that subaccount — it cannot reach the parent or other subaccounts.

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
`orders_write`	Create and update orders

Subaccount access

If your account has subaccounts, a parent-account API token can act on some or all of them. Pick the reach when you create the token — the setting only appears if your account actually has subaccounts.

Option	Reach
Parent only	Acts on the parent account. Default; every token created before this option shipped keeps this behavior.
All subaccounts	Acts on the parent account and every current and future subaccount.
Selected subaccounts	Acts on the parent account and the specific subaccounts you check when the token is created.

Subaccount reach is fixed at creation and can’t be edited later. To grant or remove reach to a subaccount, revoke the token and create a new one.

Targeting a subaccount on a request

To find the subaccounts your token can reach, call GET /v1/account without a Privy-Account-Id header. The response’s data.subaccounts list contains the reachable subaccounts; use a subaccount’s id as the Privy-Account-Id value.

curl -X GET "https://api.privy.com/v1/account" \
  -H "Authorization: Bearer privy_YOUR_TOKEN"

Include the target subaccount’s identifier in the Privy-Account-Id header alongside your normal Authorization header.

curl -X GET "https://api.privy.com/v1/contacts" \
  -H "Authorization: Bearer privy_YOUR_TOKEN" \
  -H "Privy-Account-Id: SUBACCOUNT_IDENTIFIER"

Header omitted — the request runs against the parent account.
Header present, subaccount allowed by the token — the request runs against that subaccount. Rate limits are tracked per subaccount.
Header present, subaccount not allowed by the token — the request returns 403 forbidden.

Using a token

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

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 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
`403`	`forbidden`	Token was used with a `Privy-Account-Id` header for a subaccount it does not have reach to

See the Errors page for all error codes.

API Reference

Contacts

Orders

Events

Creating a token

Token format

Scopes

Subaccount access

Targeting a subaccount on a request

Using a token

Expiration

Revoking a token

Limits

Error responses

​Creating a token

​Token format

​Scopes

​Subaccount access

​Targeting a subaccount on a request

​Using a token

​Expiration

​Revoking a token

​Limits

​Error responses

Creating a token

Token format

Scopes

Subaccount access

Targeting a subaccount on a request

Using a token

Expiration

Revoking a token

Limits

Error responses