Concepts

API keys

Generate, scope, rotate, and revoke API keys. The token your back-end uses to authenticate with Nudgel.

Format

text

rk_live_a3f7b2c1_4Hk9mPqR2vT8XzL5wY3jN6sB1cF7gE0aD8u
└─┬─┘ └─┬┘ └────┬───┘ └──────────────┬──────────────┘
  │     │       │                    └─ secret (32 chars base62 ~190 bits)
  │     │       └─ prefix (8 hex chars, indexed for fast lookup)
  │     └─ environment (live | test)
  └─ key marker (always rk_)

The prefixis what we index in Postgres and cache in Redis (60s TTL) so that auth checks don't Argon2-verify on every request. The secret is hashed with Argon2id at write time and never stored in plaintext anywhere — losing it means revoking and creating a new key.

Environments — live vs test

Prefix	Environment	What happens
`rk_live_`	Production	Real provider calls. Real costs. Real customers.
`rk_test_`	Sandbox	Goes through the full pipeline but never hits a provider. No costs, no recipients.

Scopes

Default scopes for new keys:

messages:send — call the send endpoints
messages:read — query message history

Owner-only additional scope:

admin:* — manage tenant settings, providers, members. Rare; use only for IaC/Terraform automation.

Rotation

ROTATE EVERY 90 DAYS

Set a calendar reminder. Generate a new key, deploy it, wait for the old one's last_used_at to age out, then revoke the old one. Zero downtime.

Revocation

Revocation is instantaneous. We invalidate the Redis cache entry the moment you revoke, and the next request with that key gets 401 Invalid API key.

bash

curl -X DELETE \
  https://api-raven-cloud.autotribes.app/v1/admin/api-keys/$KEY_ID \
  -H "Authorization: Bearer $YOUR_ASTRA_TOKEN" \
  -H "X-App-Name: raven-cloud" \
  -H "X-Tenant-Slug: acme-co"