API keys
Every API request needs an API key. Create keys in the dashboard under API keys, or through the API with a full-access key.
Using a key
Send the key as a bearer token:
Authorization: Bearer sg_live_...Keys are secret. Use them only from your server, never in a browser or a mobile app. The full key is shown once, when you create it. After that, Spamgone shows only a short prefix such as sg_live_AbCd, and stores nothing that can be turned back into the key.
Modes
| Mode | Prefix | What it does |
|---|---|---|
live |
sg_live_ |
Real checks, counted toward your plan. |
test |
sg_test_ |
Fixed results that are never counted and never call the AI model. For building and for CI. |
A test key can only create, rotate or revoke other test keys, so a leaked one can't affect live traffic.
Permissions
| Permission | Allowed |
|---|---|
full_access |
Every team endpoint that isn't for admins only, including managing keys. |
check_only |
Creating checks, sending feedback on its own checks, and the Perspective-compatible endpoints. |
Give the key inside your app check_only, so a leak can't be used to read your history or manage your account.
Managing keys through the API
All of these need a full-access key.
| Method and path | What it does |
|---|---|
POST /v1/api-keys |
Creates a key from name, mode (default live) and permission (default full_access). The response includes token, the full key, once. |
GET /v1/api-keys |
Lists the keys that still work, with prefix, last_used_at and request_count. |
DELETE /v1/api-keys/{id} |
Revokes a key. It stops working within a minute. |
POST /v1/api-keys/{id}/rotate |
Creates a new key with the same name, mode and permission. Send overlap_seconds (up to 86400) to keep the old key working that long. |
Each plan sets how many keys that still work a team can have: 25 on Free and Pro, 100 on Scale, and no limit on Enterprise. People must verify their email address before they create keys.
Usage
last_used_at and request_count update within a minute of each request.
Errors
name |
Status | Meaning |
|---|---|---|
missing_api_key |
401 | No key was sent in the Authorization header. |
invalid_api_key |
403 | The key is unknown, revoked or past its rotation overlap. |
restricted_api_key |
403 | The key's permission or mode doesn't allow this request. |
api_key_limit_reached |
422 | The team already has the most keys its plan allows. |
email_not_verified |
403 | The person creating the key hasn't verified their email address. |