Skip to main content
API keys authenticate the CLI and the raw /api/v1 surface. The hosted MCP server uses OAuth instead, so you do not need a key for it.

​
Create a key

In the ContentHero app, go to Settings, API Keys and create a key. You see the full secret once, at creation time. Copy it then; it is stored hashed and cannot be revealed again later through the same view. Keys are prefixed ch_live_. Treat a key like a password.

​
Scopes

Every key is scope-gated. Grant only what the integration needs. If a call fails on a missing scope, the response tells you which scope to grant. Add it in the same API Keys view. Do not work around a missing scope.

​
Use a key

The recommended path is contenthero login, which provisions and stores a key for you. To use an existing key, set it in the environment:
Resolution order is --api-key flag, then CONTENTHERO_API_KEY, then the stored credential at ~/.contenthero/credentials (mode 0600).

​
Rate limits and idempotency

  • Requests are rate-limited per key. Over the limit returns 429. Back off and retry.
  • Generation accepts an idempotency key so a retried request does not double-charge. The SDK and CLI handle this for you.

​
Rotate and revoke

Rotate keys periodically and whenever one may be exposed. Revoking a key is immediate and is a soft delete; in-flight requests using it stop authenticating. Issue a fresh key before revoking the old one to avoid downtime.
Never paste a key into an agent chat, a commit, or a log. The CLI and MCP exist so the key never has to appear in a prompt.