> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motion.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

The Motion API uses bearer tokens for video jobs and automations.

```http theme={null}
Authorization: Bearer motion_your_api_key
```

AI agents connecting over [MCP](https://docs.motion.so/guides/mcp.md) can authenticate the same way (a `motion_` API key as the bearer token), or with OAuth 2.1 — including the device flow. New agents can register with a verified user or agent email to receive a normal API key. Existing service-account `client_credentials` remain supported. See the [MCP & AI Agents guide](https://docs.motion.so/guides/mcp.md).

## API key ownership

Each `motion_` API key belongs to the person who created it. On an organization account, create the key for the workspace the integration should use. The credential keeps that scope; sending a different workspace ID does not expand its access.

* A personal key runs against the personal account and its billing.
* A workspace key uses that organization's billing customer and records the key owner as the initiator.
* Workspace membership, roles, agent permissions and credential scopes still apply. Possessing a key does not bypass a removed membership or a deleted workspace.
* OAuth authorization asks organization users to choose an accessible workspace. A personal account without organization access does not need a company workspace to connect.
* Revoke a credential when it is no longer needed. Create a separate credential for another workspace rather than reusing one across organizations.

See [Organizations and workspaces](https://docs.motion.so/product/organizations.md) and [Organization billing](https://docs.motion.so/product/billing.md).

## Create a workspace key

For an organization-enabled account, open the API key section in **Settings**, choose the organization and workspace in the **Workspace** menu, then choose **Create key**. Give the key a name that describes its use, such as “Editorial automation”. Review its owner, workspace and billing account before creating it. Copy the key when it appears; it is shown only once.

A key acts as its creator. You cannot create one as another person. The list shows your keys for the selected workspace, not every member’s keys. Selecting a different workspace here does not move chats or existing keys.

Keys inherit your current API access in that workspace. There are no separate read-only or per-action settings for an API key. Membership checks, agent restrictions and spending limits still apply. MCP browser authorization separately shows the OAuth permissions requested by the app; approve only the access it needs.

To revoke a workspace key, choose its revoke action and type the key’s name to confirm. Connected apps lose access immediately. For a production integration, create and install a replacement key before revoking the old one. Cancelling the dialog leaves the key active.

Personal accounts without organization access keep the existing **New key** flow and do not need to select a workspace.

## Key format

Motion API keys start with:

```txt theme={null}
motion_
```

The full key is shown once when created. Store it in a secret manager or server environment variable.

## Example

```bash theme={null}
export MOTION_API_KEY="motion_your_api_key"

curl https://api.motion.so/api/motion/sessions \
  -H "Authorization: Bearer $MOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Create a short product demo video."}'
```

## Automation OAuth scopes

REST automation requests accept OAuth tokens with audience `https://mcp.motion.so/mcp`. Tokens for OpenAI, Muse, or Claude MCP resources cannot be reused for these REST routes.

Request `motion:automations:read` for definitions, capabilities, run history, and analytics; request `motion:automations:write` for creation, edits, deletion, manual runs, and retries. Session scopes do not imply automation scopes. Reauthorize existing OAuth connections to add them. API keys do not need OAuth scopes, but the account and environment must have automation access enabled.

See [Automations](https://docs.motion.so/guides/automations.md) for endpoints and examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.