Authenticate API requests
REST and MCP access use dedicated API keys tied to your VidMage account subscription. Send the key in the Authorization header.
Create and store a dedicated key
- Activate a subscription, then open the Developer Console.
- Create an API key and store it when it is shown. The console shows the full key only once.
- Provide the key to your server process or local client through its credential configuration.
Keep the credential outside page source, public repositories, logs, and chat messages. The examples in these guides read VIDMAGE_API_KEY from the process environment; the variable name is a local convention.
Send the Bearer header
Authorization: Bearer YOUR_API_KEYUse this header on capability discovery, OpenAPI downloads, upload preparation, task submission, and task queries. JSON requests also use Content-Type: application/json.
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
"https://vidmage.ai/api/v1/capabilities"This read-only discovery call is a useful first check of the credential and enabled capability set.
The separate storage PUT uses only the headers returned for that upload. Do not send your account API key to the storage URL.
Choose the recovery action from errorType
REST returns 401 NEED_API_KEY for a missing or invalid key. The MCP transport distinguishes the missing, malformed, and revoked credential codes listed below. Use the actual errorType returned by your transport.
| Response | What to change |
|---|---|
401 AUTHENTICATION_REQUIRED | Add the missing credential to the client making the request. |
401 AUTHORIZATION_HEADER_INVALID | Use exactly the Bearer header format shown above. |
401 API_KEY_INVALID_OR_REVOKED | Create a new key and replace the invalid key in the client. |
401 API_KEY_INVALID_CREDENTIAL | Replace the key; the service cannot use that stored credential. |
401 ACCOUNT_SESSION_REFRESH_REQUIRED | Sign in to VidMage once. Keep the current client key configuration. |
403 NEED_SUBSCRIBE | Activate or renew the subscription. Existing keys resume after renewal. |
Signing in again is the documented fix for ACCOUNT_SESSION_REFRESH_REQUIRED, not for every 401. For service-side credential errors and tracing, see error recovery.
Use the same access model with MCP
MCP clients use the same subscription-backed API key with the https://vidmage.ai/api/mcp endpoint. See VidMage MCP for discovery, uploads, and task tools.