Get started
Authentication
Authenticate with a campaign key in the bearer header. Learn who can manage keys, how rotation works and how to handle a 401.
Every v1 request must carry the complete Public API key inside its Authorization header. You create the key in Settings, under API, in Public API.
Key format
A generated key holds a 16-character lowercase hexadecimal identifier and a 43-character base64url secret. The whole key spans 69 characters.
Prefix in Settings displays s20_live_ and then the identifier, which comes to 25 characters in all. A request requires the whole key, the secret included.
Take the key from Public API. Keys that live under Integration keys will not authenticate a v1 request.
s20_live_<key_id>_<secret>
Send a bearer header
Point SAGA20_API_KEY at your complete key, and then attach this header to each request. Letter case does not matter in the bearer scheme.
curl "https://app.saga20.com/api/public/v1/characters" \
-H "Authorization: Bearer $SAGA20_API_KEY"
One key per campaign
Each campaign carries a single active Public API key. That key reads the public portions of that campaign. No campaign parameter exists for switching between campaigns. Make a key in every campaign you intend to read.
Creating, regenerating or revoking the key is limited to the campaign owner. Every plan offers keys. Any person who holds the whole key can send read requests for its campaign.
Regenerate or revoke a key
The whole key shows up one time after Generate key or Regenerate. Save it before you leave the page. Saga20 keeps a hash of the secret, so you cannot fetch the whole key afterwards.
Confirming Regenerate swaps in a new key and the old one stops working right away. Copy the replacement and update each tool that still uses the old key. Confirming Revoke stops the key working right away, and a fresh key can be generated afterwards.
For the precise Settings steps, see Create and manage a Public API key.
Keep the key server side
Keys belong in a server environment or a private secrets store. Leave them out of browser code and public repositories.
The v1 API leaves CORS off. A browser sitting on another origin cannot reach it with an authorization header. Send requests from your server or a command-line tool.
Handle a 401
A key that is missing, wrong, unknown or revoked gives back the same response. Wrong authorization schemes and tokens beyond 256 characters also give it back. Verify that you sent the whole current key for the campaign.
The response carries WWW-Authenticate: Bearer realm="public-api" and no rate-limit headers. Repeated invalid requests can give back 429 under the invalid-authentication limit.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="public-api"
{"error":"Invalid API key"}