# EzUGC API Authentication

EzUGC's public API authenticates with a paid-account API key (`ezk_live_...`), not OAuth. Keys are minted in the dashboard for Startup, Growth, or Pro accounts with payment_status=paid. There is no trial key and no anonymous generation route.

## Discover

How agents find the real auth method:

- This page (HTML): https://www.ezugc.ai/docs/auth
- This page (markdown): https://www.ezugc.ai/docs/auth.md
- OpenAPI securitySchemes at https://api.ezugc.ai/openapi.json (`bearerAuth`, `apiKeyAuth`, and named `apiKeyScopes`)
- Protected resource metadata (RFC 9728) at https://api.ezugc.ai/.well-known/oauth-protected-resource — bearer API keys for resource https://api.ezugc.ai.
- Create a key: https://app.ezugc.ai/dashboard/apps/mcp

There is no public OAuth authorization server, register_uri, or claim_uri. Do not call /authorize, /token, or /register.

## Pick a method

Use one header. Both send the same dashboard-issued key:

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

There is no OAuth client, client_id, or redirect for the public API. Do not call /authorize, /token, or /register for /api/public jobs.

## Use the credential

1. Subscribe to Startup, Growth, or Pro.
2. Create an `ezk_live_` key in the dashboard.
3. Send it on every functional request to https://api.ezugc.ai.
4. Confirm with `GET /api/public/me`.

```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.

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 and in RFC 9728 `scopes_supported`. Missing scopes return 403 PUBLIC_API_SCOPE_DENIED.

## Errors

- `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.

Failures return `application/json` with `{ error, code, message, hint }`.

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.

- Docs: https://www.ezugc.ai/docs
- Portal: https://www.ezugc.ai/developers
- OpenAPI: https://api.ezugc.ai/openapi.json
- MCP Streamable HTTP: https://api.ezugc.ai/mcp
- AGENTS.md: https://www.ezugc.ai/AGENTS.md