Authentication

Every endpoint except /health and the public catalogue routes requires a bearer token.

header

Authorization: Bearer gzo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Two kinds of token

Type	Prefix	Use for	Expires
API key	gzo_	Server-to-server integrations. Scoped, rate-limited, revocable independently.	Never, unless you set an expiry
Session token	—	Short-lived access from `POST /v1/auth/login`, for first-party apps.	On logout

Prefer API keys for anything that runs unattended. They can be revoked without disturbing your login sessions.

Creating a key

From the keys page, or programmatically:

POST /v1/api-keys

{
  "name": "prod-web",
  "abilities": ["generate:text", "generate:image"],
  "rate_limit_per_minute": 60,
  
  "expires_at": "2027-01-01T00:00:00Z"
}

The response contains the full key in key. This is the only time it is returned.

Scoping a key

abilities restricts what a key may call. A key issued to a marketing site that only needs images should not be able to spend on video.

Ability	Grants
generate:text	`POST /v1/generate/text`
generate:image	`POST /v1/generate/image`
generate:video	`POST /v1/generate/video`
generate:audio	`POST /v1/generate/audio`
read:history	Generation history and lookups
read:credits	Balance, usage and estimates
*	Everything (default when `abilities` is omitted)

Spend caps

One limit applies per key today, with a second planned.

rate_limit_per_minute — requests per minute. Exceeding it returns 429.
Planned monthly_credit_cap — a per-key monthly credit ceiling. Not yet available; today a key is bounded by the account balance.

Treat a key as full account access. A key today can spend the whole account balance — per-key spend caps are on the roadmap, not shipped. Use one key per environment and revoke immediately on any suspicion of exposure.

Revoking

DELETE /v1/api-keys/{id}

curl -X DELETE https://api.genzoai.com/v1/api-keys/12 \
  -H "Authorization: Bearer $GENZO_API_KEY"

Revocation is immediate and irreversible. In-flight requests finish; new ones get 401.

Handling secrets

Read keys from environment variables or a secret manager, never from source.
Use a distinct key per environment so revoking staging never takes down production.
Rotate on any suspicion of exposure — create the replacement, deploy, then revoke the old one.
Never expose a key to a browser or mobile client. Proxy through your own backend.