Authentication & API tokens

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. On Advanced and Professional plans, navigate to Settings > Billing to purchase the Write API add-on. It isn’t offered on Basic plans; upgrade your plan or contact support@buttercms.com for assistance.

Where to find your tokens

Navigate to Settings > General in your ButterCMS dashboard and look for the API Tokens section. API Tokens Tab in Settings

Authentication methods

Method 1: query parameter

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

Operation	Query Parameter	Header Authentication
Read (GET requests)	✅ Supported	✅ Supported
Write (POST/PUT/PATCH/DELETE)	⚠️ Accepted, but not recommended	✅ Recommended

The auth_token query parameter works with Write tokens too, but avoid it for write operations: query strings get logged by servers and proxies and can end up in browser history or Referer headers, leaking a write-capable token. Always send Write tokens via the Authorization header instead.

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: The exact message depends on the endpoint. Most Read API endpoints (Pages, Blog Posts, blog metadata, feeds, /v2/content/?keys= and single collection items) return:

{
  "detail": "Incorrect authentication credentials."
}

Write requests, GET /v2/content/{key}/ and GET /v2/pages/search/ return:

{
  "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
✅ If you suspect compromise, reset your Read token from Settings > General, or contact support@buttercms.com to rotate a Write token

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 on Advanced and Professional plans (not on Basic). To enable it:

Navigate to Settings > Billing in your ButterCMS dashboard
Click on Get Details and Upgrade under the add-ons section
Select the Write API add-on to purchase

Next steps

REST Endpoints

Explore available API endpoints

Request/Response Format

Understand JSON data structures

Error Handling

Handle authentication errors

Overview

Read API

Write API

Webhooks API

Image API

Authentication & API tokens

Token types

Read API token

Write API token

Where to find your tokens

Authentication methods

Method 1: query parameter

Method 2: authorization header (read & write operations)

Authentication by operation type

Code examples

Authentication errors

401 Unauthorized

Security best practices

Do’s

Don’ts

Environment configuration

Requesting a write token

Next steps

REST Endpoints

Request/Response Format

Error Handling

​Token types

​Read API token

​Write API token

​Where to find your tokens

​Authentication methods

​Method 1: query parameter

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

​Authentication by operation type

​Code examples

​Authentication errors

​401 Unauthorized

​Security best practices

​Do’s

​Don’ts

​Environment configuration

​Requesting a write token

​Next steps

REST Endpoints

Request/Response Format

Error Handling

Token types

Read API token

Write API token

Where to find your tokens

Authentication methods

Method 1: query parameter

Method 2: authorization header (read & write operations)

Authentication by operation type

Code examples

Authentication errors

401 Unauthorized

Security best practices

Do’s

Don’ts

Environment configuration

Requesting a write token

Next steps