Reference

Authentication

Saperly has two auth patterns:

  • API keys for programmatic access
  • browser session auth for parts of the web portal

For integrations, use API keys.

Auth header

$Authorization: Bearer sk_live_...

SDK authentication

1import { Saperly, SaperlyError } from "@saperly/sdk";
2const saperly = new Saperly({ apiKey: process.env.SAPERLY_API_KEY! });
Read your API key from an environment variable like SAPERLY_API_KEY. Pass it explicitly to the SDK constructor. The SDKs do not auto-read env vars.
Never hardcode API keys in source code. Use environment variables or a secrets manager.

Get an API key

Sign up at saperly.com/login. Enter your email and click the magic link sent to your inbox. No password needed. You can also sign in with Google or GitHub.

New accounts receive a default live API key and a $5 free signup credit (never expires). Your API key is shown once on the welcome screen. Copy and store it immediately.

If you missed the key on the welcome screen, create a new one from the dashboard or via the API below.

Create another API key

From the dashboard, go to Settings → API Keys → Create key.

Or via the API (requires a browser session cookie):

$curl -X POST https://saperly.com/api/v1/auth/keys \
>  -H "Content-Type: application/json" \
>  -b "session=YOUR_SESSION_COOKIE" \
>  -d '{
>    "name": "production key",
>    "environment": "live"
>  }'

Service keys (root credentials)

For programmatic key management (an agent that mints, rotates, and revokes API keys at runtime), use a service key instead of a regular API key.

  • Service keys are minted only in the portal at /settings/keys → Service Keys.
  • They CAN call /v1/keys to manage child API keys.
  • They CANNOT place calls or send messages.
  • They cannot mint other service keys via the API; a leaked service key cannot bootstrap another.

Service keys use prefix sk_svc_test_ / sk_svc_live_ and are sent on the wire the same way as regular keys:

$Authorization: Bearer sk_svc_live_...

See Service keys for the full model, the permissions reference, and the mint / rotate / revoke flow.

Key environments

  • sk_live_... for production traffic
  • sk_test_... for sandbox or test traffic

Rotate keys safely

1

Create a new key

POST /api/v1/auth/keys with the same environment.
2

Update your application

Deploy the new key to your server or config.
3

Verify traffic flows

Confirm calls and webhooks still work with the new key.
4

Revoke the old key

Delete or revoke the old key from the dashboard.
Revoking a key is immediate. Any in-flight API calls using the old key will fail. Always deploy the new key first.

Advice

Use separate keys for:

  • local development
  • staging
  • production
  • one-off scripts

That makes revocation survivable.