Documentation Index
Fetch the complete documentation index at: https://docs.moda.app/llms.txt
Use this file to discover all available pages before exploring further.
Authentication (REST API)
Authorization: Bearer moda_live_<suffix>
Moda-Version: 2026-05-01.
Creating a key
- Open the Moda app → Settings → Developer → REST API → Create Key.
- Name the key for the integration it belongs to (“CI Pipeline”, “Slack bot”).
- Select the minimum scopes the integration needs (table below).
- Copy the key immediately — it’s shown once.
- 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 | Grants |
|---|
canvases:read | List and search canvases |
canvases:write | Make canvases public (share links); other write ops through tasks/remix |
designs:read | Fetch canvas pseudo-HTML, tokens, page metadata |
designs:export | Export PNG / JPEG / PDF / PPTX |
tasks:read | Get task status; list tasks |
tasks:write | Start design + remix tasks |
tasks:cancel | Cancel in-flight tasks |
brand_kits:read | List brand kits |
brand_kits:write | Create, update, delete brand kits; attach images |
uploads:write | Upload files (multipart + from-URL) |
organizations:read | List organizations and teams |
credits:read | Check credit balance |
webhooks:manage | Webhook configuration (future) |
Scope recipes by integration type
| Integration | Scopes |
|---|
| Read-only dashboard (list canvases, show tokens) | canvases:read, designs:read, organizations:read |
| Scheduled design generator with Slack webhook | brand_kits:read, uploads:write, tasks:write, tasks:read, designs:export, canvases:read |
| Export pipeline (every canvas → S3) | canvases:read, designs:export |
| Theme regeneration in CI | designs:read |
| Full-service automation | all scopes (least recommended — split by integration) |
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
| Status | Meaning |
|---|
401 authentication | Missing, invalid, revoked, or expired key |
403 permission | Valid key, but missing the scope for this endpoint, or resource belongs to a different team |
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
