API

Authentication

Create, scope, rotate, and cap a key.

Create a key

In Hawkeye, open Settings, then API keys. You can hold 10 keys. The secret starts with hk_live_ and is shown once. Hawkeye stores a SHA-256 of it, not the secret.

Agents

Choose every agent on the account (*) or a list of agent ids. A key cannot call an agent that is not on that list. The error is 403 agent_denied.

Capabilities

Anything you do not grant is denied. The names are:

• text — Conversations, and the OpenAI-compatible chat endpoint.
• image — Image generation.
• video — Video generation.
• voice — Phone numbers, calls, the bridge, and transcripts.
• files — Image and PDF uploads.
• projects — Projects and queued tasks.
• tools — List tools and invoke one plugin tool.
• agents — List agents this key may use.
• admin — Create an agent. The router chooses the model.
• secrets — List and save Secret Manager items. Values are not returned; that also needs secrets_reveal.

everything grants all of the above. Older keys stored chat, which is the text capability only. file-upload is stored as files and file_upload is stored as files. chat is accepted and stored as text.

Rotate, revoke, and edit

Rotate when the secret might have leaked. The old secret stops immediately and the new one is shown once. Revoke stops a key immediately. You can change scopes, the agent list, the request limit, and the credit cap without rotating.

Rate limit and credit cap

A new key allows 60 requests a minute unless you set another number. The ceiling is 600. The limit is a rolling 60-second window. Over the limit, the partner API returns 429 rate_limited and a Retry-After header of 1 second.

An optional monthly credit cap is counted in UTC calendar months. Past the cap, the call returns 402 spend_cap with “This key has reached its credit cap.” The account wallet is a separate check. An empty wallet returns 402 insufficient_quota.

Webhooks on the key

You can set an https URL, at most 300 characters. Hawkeye creates a signing secret that starts with whsec_ and shows it once. The secret is stored sealed. See Webhooks.