Layovelle

Authentication

Documentation

The Layovelle 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 Layovelle app and go to Settings > Developer
Under REST API, click Create Key
Give the key a name (e.g., “CI Pipeline” or “Internal Dashboard”)
Click Create — the key is granted every scope except admin (see Scopes below)
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..." \
  -H "Layovelle-Version: 2026-05-01"

Every request without a valid key returns 401 Unauthorized with WWW-Authenticate: Bearer. Pin Layovelle-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.

Scope	Grants access to
`canvases:read`	List and search canvases; enumerate drive folders and files
`canvases:write`	Create and modify canvases
`designs:read`	Fetch design pseudo-HTML, tokens, pages
`designs:export`	Export and download files
`tasks:read`	Get task status and list tasks
`tasks:write`	Start design and remix tasks
`tasks:cancel`	Cancel in-flight tasks
`brand_kits:read`	List brand kits
`brand_kits:write`	Create and update brand kits
`uploads:write`	Upload files and import from URLs
`organizations:read`	List organizations and teams
`credits:read`	Check credit balance
`webhooks:manage`	Manage webhook configuration
`publish:share`	Publish and unpublish hosted websites
`media:generate`	Metered media generation and editing (credit-checked, billed on delivery)
`web:search`	Metered web search and page read
`websites:read`	List and inspect hosted websites
`websites:write`	Create, update, and delete hosted websites
`drive:write`	Create folders; move, rename, or delete items; change visibility
`files:read`	Download file contents
`expert:ask`	Ask-expert advisory Q&A (free, read-only)
`admin`	Reserved for organization-admin verbs (opt-in only, never granted by default)

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.

# Both of these work for path parameters:
curl -X POST https://api.moda.app/v1/canvases/cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV/export ...
curl -X POST https://api.moda.app/v1/canvases/550e8400-e29b-41d4-a716-446655440000/export ...

# Body fields accept both forms too:
curl -X POST https://api.moda.app/v1/remix \
  -d '{"canvas_id": "550e8400-e29b-41d4-a716-446655440000"}'

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 Layovelle-Version header.

Authentication

​Creating an API key

​Using your key

​Scopes

​Security best practices

​Resource ID formats

​Revoking a key