Skip to main content

​
Authentication Methods

Autumn supports two types of API keys for authentication:
  1. Secret Keys - Full API access for server-side operations
  2. Publishable Keys - Limited access for client-side operations

​
Secret Keys

Secret keys provide full access to your Autumn API and should only be used in server-side code. Never expose secret keys in client-side code or public repositories.

​
Key Formats

Secret keys follow these formats based on environment:
  • Test/Sandbox: am_sk_test_...
  • Live/Production: am_sk_live_...
All secret keys must start with the am_ prefix.

​
Using Secret Keys

Include your secret key in the Authorization header as a Bearer token: 
curl https://api.autumn.example/v1/customers \
  -H "Authorization: Bearer am_sk_test_YOUR_SECRET_KEY"

​
Example with Different Languages

curl https://api.autumn.example/v1/customers \
  -H "Authorization: Bearer am_sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"

​
Publishable Keys

Publishable keys provide limited, read-only access to specific endpoints and can be safely used in client-side code.

​
Key Formats

  • Test/Sandbox: am_pk_test_...
  • Live/Production: am_pk_live_...

​
Allowed Endpoints

Publishable keys can only access these endpoints:
MethodEndpointDescription
GET/v1/productsList products
POST/v1/entitledCheck entitlements
POST/v1/checkCheck feature access
GET/v1/customers/:customer_idGet customer details

​
Using Publishable Keys

curl https://api.autumn.example/v1/products \
  -H "Authorization: Bearer am_pk_test_YOUR_PUBLISHABLE_KEY"
Attempting to access restricted endpoints with a publishable key will return a 401 Unauthorized error with code endpoint_not_public.

​
Dashboard Authentication

Requests from the Autumn dashboard use Better Auth session-based authentication instead of API keys. These requests include the x-client-type: dashboard header.

​
Environment-Based Keys

Autumn automatically determines the environment (sandbox or live) based on your API key:
  • Keys starting with am_sk_test_ or am_pk_test_ → Sandbox environment
  • Keys starting with am_sk_live_ or am_pk_live_ → Live environment
This ensures complete data separation between test and production environments.

​
Authentication Errors

Common authentication errors you may encounter:
Error CodeStatusDescription
no_secret_key401No Authorization header provided
invalid_secret_key401API key is invalid or malformed
invalid_auth_header401Authorization header format is incorrect
no_publishable_key401Publishable key missing
invalid_publishable_key401Publishable key is invalid
endpoint_not_public401Endpoint not accessible with publishable key
failed_to_verify_secret_key401Could not verify the secret key
failed_to_verify_publishable_key401Could not verify the publishable key

​
Example Authentication Error

{
  "message": "Secret key not found in Authorization header",
  "code": "no_secret_key",
  "env": "sandbox"
}

​
Best Practices

  • Never commit secret keys to version control
  • Store keys in environment variables
  • Use different keys for different environments
  • Rotate keys regularly
  • Never expose keys in client-side code or public repositories
  • Use secret keys for server-side operations
  • Use publishable keys for client-side, read-only operations
  • Use test keys during development and testing
  • Use live keys only in production
  • Implement proper error handling for 401 responses
  • Log authentication failures for security monitoring
  • Don’t expose detailed authentication errors to end users
  • Implement retry logic with exponential backoff

​
Managing API Keys

You can create and manage your API keys through the Autumn dashboard. Each organization can have multiple API keys for different purposes and environments.
For enhanced security, create separate API keys for different services or environments, and revoke keys immediately if they’re compromised.

Build docs developers (and LLMs) love

Get started for freeTalk to us