Authentication
Send the API key on every request and choose the workspace when the key reaches more than one.
Every request carries an API key. The key defines the account, the workspace and whose credits are spent.
Create a key
Open API keys and click New key. The key appears only once: copy it and store it in your secrets vault. API keys are available on the Gratuito, Básico, Plus, and Pro plans.
The key spends credits and publishes to the workspace's connected accounts. Keep it on the server, in an environment variable. Never in the browser, in the app or in the repository.
Send the key
Use the X-Api-Key header:
curl https://api.cut.pro/api/v1/workspace \
-H "X-Api-Key: $CUTPRO_API_KEY"Or Authorization: Bearer, if your HTTP client already builds that header:
curl https://api.cut.pro/api/v1/workspace \
-H "Authorization: Bearer $CUTPRO_API_KEY"A missing, revoked or expired key returns 401:
{ "code": "UNAUTHORIZED" }A blocked account returns 403 with ACCOUNT_BLOCKED. In that case no key on the account works: contact support.
Workspaces
Credits, videos, clips, renders and connections belong to a workspace. A key is tied to one or more workspaces, and each request operates on exactly one.
Key with one workspace
Nothing to do. Every request lands on the key's workspace.
Key with more than one workspace
Send X-Workspace-Id on every request:
curl https://api.cut.pro/api/v1/balance \
-H "X-Api-Key: $CUTPRO_API_KEY" \
-H "X-Workspace-Id: 7401220118845503"Without the header, the API returns 400 and lists the workspaces the key reaches:
{
"code": "MISSING_WORKSPACE_ID",
"extra": { "allowed_workspace_ids": ["7401220118845503", "7401220118845991"] }
}An id outside that list returns 400 WORKSPACE_NOT_AUTHORIZED, with the same list in extra.
To find out which workspace the request landed on, with plan and role, call GET /workspace.
Social accounts
To publish, the workspace needs connected accounts. GET /connections lists the existing ones and returns the id that goes in connection_id on the post. Missing a network? GET /connections/link?platform=tiktok returns a Cut.Pro link that opens the login for that network. Hand the link to the person, wait for them to come back and list again. See Publishing.
Best practices
- One key per integration. If one leaks, you revoke only that one.
- Revoke what you do not use. The keys page shows every key, and revoking takes effect immediately.
- Do not log the header. Many HTTP clients write headers in debug mode.