Skip to main content

​
Token types

ButterCMS provides two types of API tokens for different operations:

​
Read API token

Used for fetching content from the API. This token is safe to use in client-side code and public applications. API Token Settings

​
Write API token

Used for creating, updating, and deleting content. This token must be kept secure and should never be exposed in client-side code.
The API token you use for reading from the ButterCMS API will not allow you to create content. For write operations, you need a separate write-enabled token. Navigate to Settings > Billing to purchase the Write API add-on, or contact support@buttercms.com for assistance.

​
Where to find your tokens

Navigate to the Settings page of your ButterCMS dashboard to view your tokens in the API Tokens tab. API Tokens Tab in Settings

​
Authentication methods

​
Method 1: query parameter (read operations only)

Pass your API token via the auth_token parameter on every request: 
curl "https://api.buttercms.com/v2/posts/?auth_token=your_read_api_token"

​
Method 2: authorization header (read & write operations)

Set the Authorization header to Token your_api_token: 
curl -H "Authorization: Token your_api_token" \
     "https://api.buttercms.com/v2/posts/"
The header value must include the Token prefix before your actual token.

​
Authentication by operation type

OperationQuery ParameterHeader Authentication
Read (GET requests)✅ Supported✅ Supported
Write (POST/PUT/PATCH/DELETE)❌ Not Supported✅ Required

​
Code examples

// Using query parameter (Read operations)
const response = await fetch(
  `https://api.buttercms.com/v2/posts/?auth_token=${process.env.BUTTER_READ_TOKEN}`
);

// Using header (Read or Write operations)
const response = await fetch('https://api.buttercms.com/v2/pages/', {
  method: 'POST',
  headers: {
    'Authorization': `Token ${process.env.BUTTER_WRITE_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(pageData)
});

​
Authentication errors

​
401 Unauthorized

Returned when the API token is missing, invalid, or insufficient for the operation. Missing token: 
{
  "detail": "Authentication credentials were not provided"
}
Invalid token: 
{
  "detail": "Invalid token."
}
Common causes:
  • Missing auth_token parameter or Authorization header
  • Invalid or expired API token
  • Using a Read token for Write operations

​
Security best practices

Your write-enabled token should never be used anywhere it would be exposed, such as in client-side JavaScript.

​
Do’s

  • ✅ Store tokens in environment variables
  • ✅ Use the Read token for public-facing applications
  • ✅ Keep Write tokens on secure backend servers only
  • ✅ Use HTTPS for all API requests
  • ✅ Rotate tokens periodically if you suspect compromise

​
Don’ts

  • ❌ Never commit tokens to version control (GitHub, GitLab, etc.)
  • ❌ Never expose Write tokens in client-side code
  • ❌ Never share tokens in public forums or documentation
  • ❌ Never log tokens in application logs

​
Environment configuration

# .env
BUTTER_READ_TOKEN=your_read_api_token_here
BUTTER_WRITE_TOKEN=your_write_api_token_here

​
Requesting a write token

Write API is available as a paid add-on. To enable it:
  1. Navigate to Settings > Billing in your ButterCMS dashboard
  2. Click on Get Details and Upgrade under the add-ons section
  3. Select the Write API add-on to purchase
Enable Write API

​
Next steps

REST Endpoints

Explore available API endpoints

Request/Response Format

Understand JSON data structures

Error Handling

Handle authentication errors