Skip to main content
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

  1. Open the Moda app and go to Settings > Developer
  2. Under REST API, click Create Key
  3. Give the key a name (e.g., “CI Pipeline” or “Internal Dashboard”)
  4. Select the scopes the key needs (see Scopes below)
  5. Click Create
  6. 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:
Every request without a valid key returns 401 Unauthorized with WWW-Authenticate: Bearer. Pin Moda-Version on every request so your response shapes stay stable across releases — see Versioning.

​
Scopes

Each API key is granted one or more scopes that control what it can access. Choose the minimum scopes your integration needs. For example, a read-only dashboard integration would need canvases:read and designs:read. An automation that generates designs would also need tasks: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.

​
Resource ID formats

Every resource has a prefixed wire ID like cvs_01HT9WK8... (canvas), task_01HT9WK8... (task), bk_01HT9WK8... (brand kit). The prefix disambiguates the resource type on sight and prevents accidental cross-resource lookups. Two rules, different strictness:
  • JSON request / response body fields — strict. Always the prefixed form (cvs_..., task_..., etc.). Sending a bare UUID in a body field returns 400 invalid_request.
  • Path parameters — tolerant. Accept either the prefixed form or a bare UUID string (550e8400-e29b-41d4-a716-446655440000). Pass a UUID straight from your database or a tool response without re-encoding.
Response id fields always come back prefixed, so stored references should prefer the prefixed form. The bare-UUID path-parameter tolerance is a convenience for integrators who already hold UUIDs.

​
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.
  • Versioning — pin a version with the Moda-Version header.