Skip to main content

​
Authentication (REST API)

Every request. Always pair with Moda-Version: 2026-05-01.

​
Creating a key

  1. Open the Moda app → Settings → Developer → REST API → Create Key.
  2. Name the key for the integration it belongs to (“CI Pipeline”, “Slack bot”).
  3. Select the minimum scopes the integration needs (table below).
  4. Copy the key immediately — it’s shown once.
  5. Copy the webhook signing secret shown in the same banner. This is used to verify webhook payloads. You cannot retrieve it later.
Keys start with moda_live_. They are hashed at rest; only the prefix is safe to log. Lost a key? Revoke it and create a new one.

​
Scopes (13)

​
Scope recipes by integration type

​
Security best practices

  • Keep keys server-side. Never expose them in frontend code, mobile apps, or client bundles.
  • One key per integration. Revocation affects one system; rotation doesn’t cascade.
  • Narrow scopes. A read-only dashboard shouldn’t have tasks:write.
  • Rotate on a schedule or after any suspected leak. Revoke in the app; issue a fresh key; update config.
  • Store in a secret manager. .env works for local dev; production should use Vault / AWS Secrets Manager / GCP Secret Manager / Doppler.
  • Log the request_id from error envelopes — it’s how support finds your request in logs. Don’t log the key itself.

​
Revoking

Settings → Developer → REST API → Delete. Takes effect immediately. All requests using that key return 401 Unauthorized instantly.

​
Errors

Both come with a WWW-Authenticate: Bearer header. Errors carry the standard typed envelope; see errors.md.

​
Common wrong guesses

  • Committing a moda_live_… key to a repo. Even private repos leak eventually. Use env vars + a secret manager.
  • Over-scoping. webhooks:manage on a key that only exports is over-privileged. Narrow.
  • Logging the full key for debugging. Only log the prefix (moda_live_) — the suffix is a secret.
  • Using the same key across production and staging. Keys should be environment-specific so you can revoke independently.
  • Forgetting the webhook signing secret. It’s shown once alongside the key. Store it adjacent to the key in your secret manager — you’ll need it to verify webhook payloads.

​
Upstream