API Keys

Overview#

API keys let an external client — a script, a server, an agent — call a small set of read-only endpoints as your account, without a browser session. Each key carries its own name, an explicit set of scopes, an optional restriction to specific projects, and an expiry. Keys are managed entirely in the Studio; there is no endpoint to create or list keys with a key.

Creating a key#

Open your account menu in the Studio header and choose API access (/account/api-keys). From there:

1. Give the key a name — this is only for you to recognize it later.
2. Check the scopes it needs (see below). A key holds at least one.
3. Optionally restrict it to specific projects. Leaving this empty allows the key to see every project you own.
4. Choose an expiry — 30, 90, or 365 days, or never.
5. Create the key.

Scopes#

A key's scopes limit what it may do, independently of what the account itself can do. A request needs every scope its endpoint requires.

The key-creation form also offers six further scopes — project:create, media:upload, project:edit, agent:author, library:install, and export:read — for uploading, editing a project's document by hand (POST /api/v1/projects/{videoId}/changes), asking the agent to author it, installing custom user: plugins into a project (POST /api/v1/projects/{videoId}/plugins), and exporting projects without Studio. project:edit and agent:author are deliberately separate: a key that may start agent runs cannot thereby rewrite sections by hand, nor the reverse. None of the endpoints on this page use them; the ones the Agent API needs are listed with each of its routes.

Using a key#

Send the secret as a Bearer token. There is no other way to authenticate these endpoints — no cookie, no query parameter.

curl "https://api.mp4e.com/api/v1/whoami" \
  -H "Authorization: Bearer mp4e_sk_..."

GET /api/v1/whoami — identifies the key. No scope required; this is the first call any integration makes.

{
  "userId": "b3f2b6b0-...",
  "keyId": "9e1c9a44-...",
  "name": "reporting script",
  "scopes": ["project:read"],
  "projectIds": null
}

GET /api/v1/projects — the projects this key may see (scope project:read). When the key is restricted to specific projects, the list only includes those.

curl "https://api.mp4e.com/api/v1/projects" \
  -H "Authorization: Bearer mp4e_sk_..."

{
  "projects": [
    {
      "videoId": "6c2a1a10-...",
      "title": "Product Demo",
      "revision": 4,
      "updatedAt": "2026-09-01T12:34:56Z"
    }
  ]
}

GET /api/v1/projects/{videoId} — a project's header and a count of items per section (scope project:read). This returns a summary only — no metadata document, no schema.

curl "https://api.mp4e.com/api/v1/projects/6c2a1a10-..." \
  -H "Authorization: Bearer mp4e_sk_..."

{
  "videoId": "6c2a1a10-...",
  "title": "Product Demo",
  "revision": 4,
  "video": {
    "title": "Product Demo",
    "fps": 30,
    "width": 1920,
    "height": 1080,
    "duration": 42.3
  },
  "summary": {
    "overlays": 6,
    "variables": 3,
    "rules": 2
  }
}

Errors#

Security notes#

• The full secret is shown exactly once, at creation. It cannot be recovered afterward — only a masked prefix is ever shown again.
• MP4E stores a hash of the secret, never the secret itself.
• Revoking a key is permanent. To rotate credentials, create a new key first, switch your integration over to it, then revoke the old one.
• Restricting a key to specific projects limits the blast radius if it leaks — prefer it over an unrestricted key wherever practical.
• Set the shortest expiry that fits your use — an expired key stops working automatically, with no action required from you.