Authentication

There are two ways in. Assistants sign in with OAuth, and the MCP server accepts the token they get. Scripts, applications and any MCP client use an API key created in your Ghostmotion workspace; both MCP and the HTTP API accept it in the same header.

HTTP header

Authorization: Bearer YOUR_API_KEY

X-API-KEY is not supported.

Signing in from an assistant (OAuth)

An assistant connecting to /mcp without a key receives a 401 whose WWW-Authenticate header points to the protected resource metadata. From there it finds Ghostmotion’s authorization server, registers itself and sends you to sign in. The flow is OAuth 2.1 authorization code with PKCE (S256) and dynamic client registration.

Discovery

https://app.ghostmotion.ai/.well-known/oauth-protected-resource/mcp
https://app.ghostmotion.ai/.well-known/oauth-authorization-server

You approve the connection for your current team, with its permissions and an optional spending limit. Access tokens last an hour and are refreshed by the assistant; they work only on the MCP server, not the HTTP API. A connection has the same permissions and limits as an API key: projects:read, videos:write, a per-run cap and an allowance. Disconnect it in Settings → Integrations or from the assistant.

Create a key for each integration

Create a key, name the integration, choose its permissions, set its limits and choose an expiry. Copy the secret immediately: Ghostmotion shows it only once.

Save the key where the client runs

Terminal

export GHOSTMOTION_API_KEY='YOUR_API_KEY'

This sets the variable for the current terminal and processes started from it. For a deployed application, put the value in its secret settings. For a generic MCP client, put it in that client’s protected header or token settings. Never put it in browser code, shared source files or assistant chat.

Permissions and identity

projects:read allows project listing, run results and video links. videos:write allows creation, edits, cancellation and preparing uploads. Use both for a complete create-and-download workflow. A reviewer can only create read-only keys.

A key acts as the person who created it in their workspace. Seeing a teammate’s project does not grant permission to direct it. Only its original author can send edits or stop its runs.

Lost, expired or revoked keys

A lost key cannot be recovered; create a replacement and update the integration. Revoking a key stops new access, invalidates its media access and asks runs started with that key to stop. Leaving the workspace also invalidates access. Revoke unused keys, and disconnect assistants you no longer use, from Integrations.