Skip to main content

Managing API keys

An API key proves your application's identity to the Nerve edge gateway (api.nervly.io).

Dashboard role prerequisite

Creating, viewing, or revoking API keys requires the Owner or Admin role in your workspace. See Roles and permissions.

Live vs. Test keys​

Nerve provides separate keys for production and development:

  • Live keys (nerve_sk_live_...): Deliver real notifications through your connected providers.
  • Test keys (nerve_sk_test_...): Simulate deliveries with synthetic responses (nerve_test_{event_id}) without dispatching external SMS, emails, or push notifications.

Creating an API key​

  1. Sign in to app.nervly.io.
  2. Click Developers in the left sidebar navigation.
  3. Click Create API Key.
  4. Enter a descriptive name (e.g. backend-production, ci-runner) and choose the environment (Live or Test).
  5. Click Create.
  6. The key is presented in an explicit Reveal Dialog. Copy the key immediately and save it in your secret manager.
Reveal-once guarantee

The full plaintext key is only shown once upon creation. In PostgreSQL, Nerve stores only the SHA-256 hash. If a key is lost, revoke it and issue a new one.

Key rotation with zero downtime​

To rotate an active production key without downtime:

  1. Create the new live key in Developers.
  2. Deploy the new key to your application servers.
  3. Observe traffic flowing on the new key (the Developers page displays last_used_at timestamps for each key).
  4. Revoke the old key by clicking Revoke and confirming in the dialog.

When you revoke a key, Nerve immediately marks revoked_at = now() in PostgreSQL and deletes the key's Redis cache entry (DEL nerve:key:{id}). In-flight requests presenting the revoked key will fail immediately with 401 Unauthorized.

Next​