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"
>  }'

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.