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)
});

import requests
import os

# Using query parameter (Read operations)
response = requests.get(
    'https://api.buttercms.com/v2/posts/',
    params={'auth_token': os.environ['BUTTER_READ_TOKEN']}
)

# Using header (Read or Write operations)
response = requests.post(
    'https://api.buttercms.com/v2/pages/',
    headers={'Authorization': f"Token {os.environ['BUTTER_WRITE_TOKEN']}"},
    json=page_data
)

# Read operation with query parameter
curl "https://api.buttercms.com/v2/posts/?auth_token=your_read_token"

# Write operation with header
curl -X POST \
  -H "Authorization: Token your_write_token" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Page", "slug": "my-page"}' \
  "https://api.buttercms.com/v2/pages/"

// Using Guzzle HTTP client
use GuzzleHttp\Client;

$client = new Client();

// Read operation
$response = $client->get('https://api.buttercms.com/v2/posts/', [
    'query' => ['auth_token' => $_ENV['BUTTER_READ_TOKEN']]
]);

// Write operation
$response = $client->post('https://api.buttercms.com/v2/pages/', [
    'headers' => [
        'Authorization' => 'Token ' . $_ENV['BUTTER_WRITE_TOKEN'],
        'Content-Type' => 'application/json'
    ],
    'json' => $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

# .env or shell export
export BUTTER_READ_TOKEN=your_read_api_token_here
export BUTTER_WRITE_TOKEN=your_write_api_token_here

ENV BUTTER_READ_TOKEN=your_read_api_token_here
ENV 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