Skip to main content
The Privy API uses OAuth 2.0 bearer tokens for authentication. Every API request must include a valid token in the Authorization header.

​
How it works

  1. Create an OAuth application in your Privy dashboard to get a client ID and client secret.
  2. Exchange those credentials for an access token using the OAuth 2.0 client credentials flow.
  3. Include the access token in the Authorization header of every request.
curl -X GET "https://dashboard.privy.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Creating an OAuth application

Navigate to Settings > Apps in your Privy dashboard and create a new application. You’ll choose a name, and the application will automatically be granted both contacts_read and contacts_write scopes. When the application is created, the dashboard displays the client secret once. Copy it immediately — you won’t be able to view it again. If you lose it, you can regenerate a new secret from the application’s settings.

​
Getting an access token

Exchange your client ID and client secret for an access token by making a POST request to the token endpoint: 
curl -X POST "https://dashboard.privy.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
A successful response returns an access token: 
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "contacts_read contacts_write",
  "created_at": 1712150400
}
FieldDescription
access_tokenThe bearer token to include in API requests.
token_typeAlways Bearer.
expires_inToken lifetime in seconds. Access tokens expire after 2 hours (7200 seconds).
scopeThe scopes granted to this token.
If your client ID or secret is wrong, the API returns a 401 error with "error": "invalid_client".

​
Refreshing tokens

When your access token expires, request a new one by repeating the client credentials exchange above. There is no refresh token in the client credentials flow — simply request a new access token.

​
Scopes

Scopes control what your token can access. Both scopes are automatically granted when you create an OAuth application.
ScopeAllows
contacts_readList and filter contacts
contacts_writeCreate, update, unsubscribe, and delete contacts

​
Security tips

  • Keep credentials secret. Never share your client secret or access tokens in client-side code, public repositories, or URLs.
  • Rotate secrets regularly. Regenerate your client secret periodically from the dashboard, especially if a team member leaves.
  • Use one application per integration. This makes it easy to revoke access for a single integration without affecting others.

​
Invalid tokens

If your token is missing, expired, or malformed, the API returns a 401 unauthorized error: 
{
  "error": {
    "code": "unauthorized",
    "message": "Bearer token is missing or invalid"
  }
}
See the Errors page for all error codes.