Authentication

Jason Lee Jason Lee
3 min read

The Sitepaste API uses bearer token authentication. This guide explains how to create, manage, and use API tokens.

Requirements

  • Pro plan subscription: API tokens are exclusive to Pro users
  • Dashboard access: Tokens are created from the dashboard settings

Creating an API token

Via dashboard

  1. Log in to your Sitepaste dashboard
  2. Navigate to Settings → API Tokens
  3. Click Create New Token
  4. Give your token a descriptive name (e.g., “CI/CD Pipeline”, “Blog Publisher”)
  5. Copy the token

Token limits

  • Maximum 3 active tokens per account
  • Tokens never expire by default
  • You must revoke an existing token before creating a new one if you have 3 active tokens

Using API tokens

Include your API token in the Authorization header of every request:

curl -X POST https://sitepaste.com/api/v1/public/pages \
  -H "Authorization: Bearer sp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Post", "content": "Hello!"}'

Managing tokens

You can view, rename, and revoke your tokens from the dashboard:

  1. Go to Settings → API Tokens
  2. View all active tokens and their last used timestamps
  3. Click a token to rename it
  4. Click Revoke to permanently disable a token

Security best practices

Do

  • Store tokens securely: Use environment variables or secret management systems
  • Use descriptive names: Easily identify what each token is used for
  • Revoke unused tokens: Clean up tokens that are no longer needed
  • Monitor usage: Check lastUsedAt timestamps for suspicious activity
  • Rotate tokens periodically: Create new tokens and revoke old ones regularly

Don’t

  • Commit tokens to git: Never include tokens in source code
  • Share tokens: Each integration should have its own token
  • Use tokens in client-side code: Tokens should only be used server-side
  • Log tokens: Avoid including tokens in application logs

Environment variables

Store your token in an environment variable:

# .env file (add to .gitignore!)
SITEPASTE_API_TOKEN=sp_your_token_here

Use it in your scripts:

curl -X POST https://sitepaste.com/api/v1/public/pages \
  -H "Authorization: Bearer $SITEPASTE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Post", "content": "Hello!"}'

Error responses

Invalid or missing token

Status: 401 Unauthorized

{
  "error": "invalid or revoked token"
}

Possible causes:

  • Token is missing from the Authorization header
  • Token format is invalid (not 35 characters or missing sp_ prefix)
  • Token has been revoked
  • Token does not exist

Pro plan required

Status: 403 Forbidden

{
  "error": "API tokens require Pro plan"
}

Your subscription has expired or you’re on a free plan. Upgrade to Pro to use the API.

Token limit reached

Status: 400 Bad Request

{
  "error": "maximum 3 active tokens allowed, please revoke an existing token first"
}

You must revoke an existing token before creating a new one.

Next steps

Now that you have an API token, learn how to: