Upgrading to v0.5.7.0

This is a non-breaking release. Existing sk_test_… and sk_live_… API keys keep working unchanged. Follow the steps below only if you want to adopt the new agent-native key management surface.

When you don’t need to upgrade

Skip this guide if:

• Your integration only places calls or sends SMS using a long-lived API key.
• You don’t need to mint, rotate, or revoke keys programmatically.
• You have no agent fleet. One API key per environment is fine.

When you should upgrade

Adopt service keys if:

• You are building an agent fleet and want each agent to hold its own scoped, cap-limited child key.
• You want to mint, rotate, or revoke keys via API instead of the portal.
• You want full audit lineage from any call back to the service key that minted the credential.

Step 1. Bootstrap a service key

1. Open https://saperly.com/settings/keys.
2. Switch to the Service Keys tab.
3. Click Generate service key. The plaintext (sk_svc_live_… or sk_svc_test_…) is shown exactly once. Save it to your secrets manager as SAPERLY_SERVICE_KEY.

Step 2. Mint a child API key

$
curl -X POST https://saperly.com/api/v1/keys \
>
  -H "Authorization: Bearer sk_svc_live_..." \
>
  -H "Content-Type: application/json" \
>
  -H "Idempotency-Key: $(uuidgen)" \
>
  -d '{
>
    "name": "agent-prod",
>
    "permissions": "call_only",
>
    "monthly_cap_cents": 500
>
  }'

The response includes plaintext_key exactly once. Save it before the response leaves memory.

Step 3. Update your code

Replace process.env.SAPERLY_API_KEY with process.env.SAPERLY_SERVICE_KEY in the code paths that mint, rotate, or revoke credentials. Keep your regular API key for everything else. Service keys cannot place calls, send SMS, or mutate lines.

1
import { Saperly } from '@saperly/sdk';
2
3
// Service key for credential management
4
const svc = new Saperly({ apiKey: process.env.SAPERLY_SERVICE_KEY! });
5
const child = await svc.keys.create({ name: 'agent-prod', permissions: 'call_only' });
6
7
// Child key for runtime calls
8
const agent = new Saperly({ apiKey: child.plaintextKey });
9
await agent.calls.create({ lineId: '550e8400-e29b-41d4-a716-446655440000', toNumber: '+14155551234' });

Step 4. Update strict-schema validators

If you validate API responses against a schema, add legacy_full to the allowed values for permissions on key responses. It is read-only (you can’t set it on POST or PATCH), but it is returned for keys minted before this release.

Verify the upgrade

$
# 1. Existing API key still works
$
curl https://saperly.com/api/v1/calls?limit=1 \
>
  -H "Authorization: Bearer sk_live_..."
$
$
# 2. Mint a smoke-test child key
$
curl -X POST https://saperly.com/api/v1/keys \
>
  -H "Authorization: Bearer sk_svc_live_..." \
>
  -H "Content-Type: application/json" \
>
  -H "Idempotency-Key: $(uuidgen)" \
>
  -d '{ "name": "migration-smoke-test", "permissions": "read_only" }'
$
$
# 3. Revoke the smoke-test key
$
curl -X DELETE https://saperly.com/api/v1/keys/KEY_ID \
>
  -H "Authorization: Bearer sk_svc_live_..."
$
$
# 4. Read the audit stream with a regular API key (not the service key)
$
curl "https://saperly.com/api/v1/audit?limit=10" \
>
  -H "Authorization: Bearer sk_live_..."

Step 4’s read itself writes an audit_read event that will appear on the next read. The audit log audits its own readers.

Rollback

There is nothing to roll back. Service keys are opt-in. To stop using them, leave the existing service key in place (it costs nothing) and stop calling /v1/keys. To fully remove, revoke the service key from the portal.

Related

• Service keys. Full concept reference.
• Agent onboarding. End-to-end agent walkthrough.
• Authentication. Auth mechanism.