Choose your credential type

Every API accepts one of two credential types. Check the authentication section of each API's reference page to see which one it uses:

CredentialBest forHow it works
API keyServer-to-server callsA long-lived key you send in the Authorization header
OAuth 2.0 client credentialsUser-facing apps and short-lived accessExchange your client ID and secret for a scoped access token

API keys

Generate an API key from your application page:

  1. Open My applications and select your application.
  2. Select Generate key and give it a name, such as production or staging.
  3. Copy the key immediately. You can only see it once.

Send the key with every request:

curl "https://api.example.com/v1/orders" \
  -H "Authorization: Bearer $API_KEY"
Rotate keys regularly

Rotate keys at least every 90 days. If a key is ever exposed, revoke it from the application page right away and generate a new one.

OAuth 2.0 client credentials

If an API uses OAuth 2.0, exchange your client credentials for a short-lived access token:

curl "https://api.example.com/oauth/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET"

The response includes an access token and its expiry:

{
  "access_token": "tok_9f8e7d",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Send the token instead of the key:

curl "https://api.example.com/v1/orders" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Tokens expire after one hour. Cache them in your application and refresh them before they lapse, rather than requesting a new one on every call.

Keep your credentials safe

  • Store secrets in a secrets manager or environment variables, never in source control.
  • Use a separate key for each environment, so a staging incident never touches production.
  • Revoke keys you no longer use.

Next steps