Getting Started

Authentication

All API requests require authentication via an HTTP Bearer token. There are two types of tokens:

API keys (recommended)

API keys are the preferred method. They are hashed before storage, so the raw key is only shown once at creation time. You can create multiple named keys and revoke them individually.

HTTP header


Authorization: Token your-api-key-here

Create a key via the API:

terminal


$ curl -X POST https://serssly.com/api/v1/api_keys \
    -H "Authorization: Token $SERSSLY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "My Bot"}'

{
  "id": 3,
  "name": "My Bot",
  "token": "PspJWGiobMbKMrBUemVFbzUKN62CaFkc",
  "created_at": "2026-04-03T..."
}

Save your key

The raw token is only shown once. Store it in a password manager or as an environment variable. If you lose it, delete the key and create a new one.

Environment variable

The CLI tool and most integrations expect the key as an environment variable:

~/.bashrc or ~/.zshrc


export SERSSLY_API_KEY=PspJWGiobMbKMrBUemVFbzUKN62CaFkc

Error responses

Requests without a valid token receive a 401 Unauthorized response:


{ "error": "Bad Credentials" }