# Authentication and product keys

AiVideoEditor's UI, REST API and MCP adapter share workspace services. API clients
use a product key, not a social-network OAuth token or database credential.
Create keys at `/app/developers` after signing in to the correct workspace. Copy
the plaintext `pk_v1_…` key once and store it in a secret manager or protected
local environment. AiVideoEditor retains a hash and display prefix.

## Send a key

```bash
curl --fail-with-body -sS \
  -H "Authorization: Bearer $PUBLISHER_KEY" \
  "$PUBLISHER_API_URL/api/v1/usage"
```

Use HTTPS for a deployed origin. Keep credentials out of URLs, source control,
chat prompts, screenshots and logs. Direct storage uploads use the returned
signed URL and headers; do not forward your AiVideoEditor bearer key to storage.

## Scopes and account access

| Scope | Capability |
|---|---|
| `accounts:read` | Inspect accounts, capabilities and TikTok settings |
| `media:write` | Reserve, finalize and manage uploads |
| `posts:read` | List posts, validate drafts and observe status |
| `posts:write` | Create and edit drafts |
| `posts:publish` | Publish, schedule, cancel and retry deliveries |
| `usage:read` | Read workspace usage and plan information |
| `webhooks:manage` | Register, list and remove webhook endpoints |

Scopes are exact names, not a hierarchy. Grant only those the integration needs.
Keys may also restrict accessible account IDs. Workspace membership, effective
role, account restrictions and plan state still apply. A key with
`posts:publish` does not automatically gain draft-writing access.

The default key scope set omits `posts:publish` and `webhooks:manage`. A draft-only
agent can prepare work for review without authority to send it. Keys cannot
create other keys or change billing.

## Revocation and recovery

Revoke a compromised key in the developer UI. Review its pending-job count first:
revocation pauses unsent work as `requires_action`; it does not delete drafts.
Create a replacement with appropriate access and review pending work before
resuming. Do not assume revocation can recall a submission already sent externally.

A `401` means credentials are absent or invalid. A `403` means the authenticated
actor lacks permission or account access. Repeatedly retrying either response
will not fix it. See [errors and recovery](/docs/errors).
