# EzUGC API Authentication

EzUGC API keys are `ezk_live_` secrets minted in the dashboard for paid Startup, Growth, or Pro accounts.

Create a key: https://app.ezugc.ai/dashboard/apps/mcp

## Headers

Either header works:

```
Authorization: Bearer ezk_live_...
x-api-key: ezk_live_...
```

## Paid check on every request

API keys are issued only from the EzUGC dashboard, and only for accounts on Startup, Growth, or Pro with an active paid subscription (from $99/month). There is no trial key, guest key, or anonymous generation route.
Every call to /api/public re-checks that the account is still paid. If you cancel or the subscription lapses, leftover keys start returning HTTP 402 PUBLIC_API_SUBSCRIPTION_REQUIRED. MCP tool calls use the same key and the same check.

## Status codes

- `401 PUBLIC_API_KEY_REQUIRED` — no key, malformed key, revoked key, or expired key.
- `402 PUBLIC_API_SUBSCRIPTION_REQUIRED` — key is well-formed, account is no longer paid.
- `402 PUBLIC_API_BILLING_EXPIRED` — billing cycle ended; renew and retry.
- `403 PUBLIC_API_SCOPE_DENIED` — key is missing a required scope.

## First authenticated call

```bash
curl -sS https://api.ezugc.ai/api/public/me \
  -H "Authorization: Bearer ezk_live_YOUR_KEY"
```

`GET /openapi.json` needs no key. It is documentation only.

## Scopes

Keys carry scopes such as `ugc:write`, `video:write`, `image:write`, `jobs:read`, `account:read`, `brand:read`, and `brand:write`. Required scope is listed on each OpenAPI operation.

## MCP and OAuth

The `@ezugc/mcp` stdio package and the remote MCP connector both send this same key to `/api/public/*`. Consent for remote MCP also validates the key through the paid check. There is no separate unpaid MCP credential.

- Docs: https://www.ezugc.ai/docs
- Portal: https://www.ezugc.ai/developers
- OpenAPI: https://api.ezugc.ai/openapi.json
- Markdown twin: https://www.ezugc.ai/docs/auth.md