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. Click Create — the key is granted every scope except admin (see Scopes below)
  5. 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 carries a set of scopes that control what it can access. Audit the table below for the blast radius of a leaked key. All scopes except admin are granted by default when a key is created from Settings — there is no scope picker on that screen. Drive reads (folder list, tree, file list, file metadata) ride canvases:read; only file bytes need files:read. For example, a read-only dashboard integration only exercises canvases:read and designs:read. An automation that generates designs also exercises tasks:write and canvases:write.

​
Security best practices

  • Do not commit keys to source control. Use environment variables or a secrets manager.
  • Treat every key as fully privileged. A Settings-created key carries every scope except admin, so a leak exposes the whole surface in the table above.
  • 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. One rule for requests, one for responses:
  • Requests — tolerant. JSON body fields and path parameters both accept either the prefixed form (cvs_..., task_..., etc.) or a bare UUID string (550e8400-e29b-41d4-a716-446655440000). Pass a UUID straight from your database or a tool response without re-encoding.
  • Responses — always prefixed. Response id fields come back in the prefixed form, so stored references should prefer the prefixed form.
Two places are strict and require the typed form:
  • Drive item and folder references — the polymorphic /v1/drive/items/{item_ref} verbs (move, rename, delete), and the fld_... filters on GET /v1/drive/folders and GET /v1/drive/files. A bare UUID is ambiguous across item kinds there.
  • POST /v1/webhook_deliveries/{delivery_id}/redeliver, which wants the whd_... id and answers 404 for anything else.

​
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.