Authentication

Secure your API requests with secret keys and best practices

Payload uses API secret keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API can be performed using either HTTP Basic Auth or Bearer tokens. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

API Keys

You can view and manage your API keys in your Payload dashboard (opens in a new tab). Your API keys have different scopes and permissions depending on your account settings.

Authentication Methods

You can authenticate with either HTTP Basic Auth or Bearer tokens. Both methods are functionally equivalent.

Provide your API secret key as the basic auth username value. You do not need to provide a password.

#!/bin/bash
# HTTP Basic Auth - Use your API key as username, leave password empty
curl "https://api.payload.com/accounts" \
  -H "X-API-Version: v2.0" \
  -u secret_key_3bW9...:
 
# Note: The colon after the key tells curl to use it as username with no password

Note the colon : after the secret key. This tells cURL to use the key as the username and leave the password empty.

Include your API secret key in the Authorization header with the Bearer scheme.

#!/bin/bash
# Bearer Token - Include your API key in Authorization header
curl "https://api.payload.com/accounts" \
  -H "X-API-Version: v2.0" \
  -H "Authorization: Bearer secret_key_3bW9..."

Using SDKs

Payload provides official SDKs that handle authentication automatically when you create an authenticated session with your secret key.

setup.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Create authenticated session with your secret key
 
# Make authenticated requests
profile = pl.Profile.all()

Once you create a session, the SDK automatically includes your API key in all requests using the appropriate authentication method for the platform.

Keep your API keys secure! Never expose your secret keys in client-side code, version control systems, or public repositories. Store keys in environment variables and rotate them regularly. Monitor your API key usage in the Payload dashboard (opens in a new tab) to detect unauthorized access.

Testing Authentication

You can verify your authentication is working correctly by making a simple API request:

test.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create authenticated session with your secret key
 
# Test authentication
try:
    profile = pl.Profile.all()
    print("Authentication successful")
except payload.exceptions.Unauthorized:
    print("Authentication failed - check your API key")

A successful response indicates your authentication is configured correctly. An authentication error means you should verify your API key is correct and properly configured.

Troubleshooting

Unauthorized Error

If you receive an Unauthorized error, verify:

Your API key is correct and hasn't been revoked
You're using the correct authentication method (Basic Auth or Bearer token)
Your API key has the necessary permissions for the requested operation
You're not using a test mode key to access production data (or vice versa)

SSL Certificate Errors

If you encounter SSL certificate errors:

Ensure you're using HTTPS (not HTTP)
Verify your system's SSL certificates are up to date
Check that your client library supports modern TLS versions

Rate Limiting

Authenticated requests are subject to rate limits. If you're hitting rate limits:

Implement exponential backoff in your retry logic
Cache responses when possible to reduce API calls
Contact support if you need higher rate limits for your use case

Overview Requests