Authentication
How to create and use API keys to authenticate with the Moda REST API.
The Moda REST API uses API keys for authentication. Include your key as a Bearer token in the Authorization header of every request.
Creating an API key
- Open the Moda app and go to Settings > Developer
- Under REST API, click Create Key
- Give the key a name (e.g., "CI Pipeline" or "Internal Dashboard")
- Select the scopes the key needs (see Scopes below)
- Click Create
- Copy the key immediately -- it is only shown once
API keys use the format moda_live_<hex_chars>.
Using your key
Include the key in the Authorization header:
curl https://api.moda.app/v1/canvases \
-H "Authorization: Bearer moda_live_abc123def456..."Every request without a valid key returns 401 Unauthorized with WWW-Authenticate: Bearer.
Scopes
Each API key is granted one or more scopes that control what it can access. Choose the minimum scopes your integration needs.
| Scope | Grants access to |
|---|---|
canvases:read | List and search canvases |
canvases:write | Create and modify canvases |
designs:read | Fetch design pseudo-HTML, tokens, pages |
designs:write | Reserved for future design write access |
jobs:read | Get job status and list jobs |
jobs:write | Start design tasks |
organizations:read | List organizations and teams |
brand_kits:read | List brand kits |
brand_kits:write | Create and update brand kits |
exports:read | Export and download files |
uploads:write | Upload files and import from URLs |
For example, a read-only dashboard integration would need canvases:read and designs:read. An automation that generates designs would also need jobs:write and canvases:write.
Security best practices
- Do not commit keys to source control. Use environment variables or a secrets manager.
- Use the narrowest scopes possible. A key that only reads canvases should not have write scopes.
- Rotate keys periodically. Delete keys you no longer use from Settings > Developer.
- Use separate keys per integration. This lets you revoke access to one system without affecting others.
- Keep keys server-side. Never expose API keys in frontend code, mobile apps, or client-side bundles.
Revoking a key
Go to Settings > Developer > REST API, find the key, and click Delete. The key stops working immediately. Any requests using the deleted key return 401 Unauthorized.