Skip to main content

Managing API keys

An API key proves your application's identity to the Nervly 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​

Nervly provides separate keys for production and development:

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

Read-only vs. read-write keys​

Every key carries scopes that decide what it can do:

  • Read & write (the default): the key can read and it can send. A key that predates scopes is treated as having both.
  • Read only: the key can call diagnostic and read endpoints and the read-only MCP tools, but it cannot send.

write implies read, so a read-write key can do everything a read-only key can.

A read-only key can use:

  • the diagnostic and read endpoints — delivery status, message lookups, template listings and subscriber inspection;
  • the read-only MCP tools: gateway_status, idempotency_inspect, check_delivery_status, list_templates and verify_subscriber_channel.

It cannot call the mutating routes — POST /v1/events/trigger, POST /v1/events/bulk, subscriber preference updates or subscriber deletion — and send_notification is not advertised to it. A request that needs write from a read-only key is rejected with 403 Forbidden.

Use a read-only key for dashboards, monitoring integrations and AI agents that should inspect your workspace without the ability to notify anyone.

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), choose the environment (Live or Test), and choose the key's scopes (Read & write or Read only).
  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 or rotation. In PostgreSQL, Nervly stores only a keyed HMAC-SHA256 hash. If a key is lost, rotate it (or revoke it and issue a new one).

Key rotation with zero downtime​

The Rotate action replaces a key's secret without an integration outage, so a leaked long-lived key does not force a revoke-and-redeploy:

  1. Click Rotate on the active key and confirm.
  2. Copy the new secret from the one-time reveal dialog — like creation, it is shown exactly once.
  3. Deploy the new secret to your application servers.
  4. Watch the key's usage indicator on the Developers page. It reads Old secret still in use until the new secret authenticates, then flips to New secret in use — the signal that your services have cut over (updated within about a minute of the first request that carries the new secret). Then click Promote to revoke the old secret immediately.

The Developers page reports each secret's last-used time separately while the window is open, so you can tell which secret your traffic is actually using rather than assuming the deployment worked.

Both the old and the new secret authenticate during a bounded overlap window (24 hours). Rotation never silently invalidates the old key: it stays valid until you promote the new one or the window closes, whichever comes first. If you do nothing, the old secret stops working when the window ends. A second rotation while a window is open is refused until you promote the new key or the window closes.

When you revoke a key, Nervly immediately marks revoked_at = now() in PostgreSQL and deletes the key's Redis cache entry (DEL nervly:key:{id}). Promoting a rotation evicts the same cache entry, so the previous secret stops authenticating immediately. In-flight requests presenting a revoked key fail with 401 Unauthorized.

Next​