Guide · CompanionGuard · Published 14 November 2026 · Reviewed 14 November 2026 · By the Ingenious AI team
API Keys in CompanionGuard: Owner Keys, Bot-Owner Keys and the Usage Endpoint
The short answer
CompanionGuard issues API keys through two surfaces — an owner surface and a bot-owner surface — each supporting create, list and revoke. A resolver ties a presented key to its bot and plan so the runtime and metrics calls can authenticate, and the /api/v1/usage endpoint reports the key's usage. As with license keys, API keys are stored only as hashes: a key is shown at creation and cannot be recovered later, which is why revocation, not retrieval, is the recovery path.
What is a CompanionGuard API key?
A CompanionGuard API key is a credential that authenticates a bot's backend calls to the product's metered surfaces — the runtime and metrics APIs and the usage endpoint. Keys are created by the platform owner or by a bot's owner, can be listed and revoked, and are stored only as hashes, so the system can verify a presented key without being able to display it again.
Create the free safety kit Next guide All guides
CompanionGuard is built by Ingenious AI. A compliance toolkit — not legal advice and not a clinical service. If you are in crisis right now: US — call or text 988; UK & Ireland — Samaritans 116 123.
Two issuers, one discipline
The product exposes key management in two places: an owner surface (the platform owner's own key administration) and a bot-owner surface (a bot's owner managing keys for their bot). Both support the same lifecycle — create, list, revoke — because the security discipline is identical regardless of who holds the key: keys authenticate machine calls, they are scoped to their bot and plan context, and compromise is handled by revocation and reissue, never by 'looking up' the old secret.
The resolver is the load-bearing piece: when a call presents a key, the resolver maps it to its bot and entitlements so that runtime decisions, metrics and usage all attribute to the right bot. That attribution is what makes per-bot evidence chains and per-plan run limits coherent — a key is not a generic password but a named channel between one bot's backend and its safety record.
Hash-only storage, and what it forces
License keys in this product are stored only as hashes — the terms state a lost, unactivated key cannot be recovered — and API keys follow the same discipline. The operational consequences are features, not bugs, once you internalise them: a database leak does not leak usable keys; support cannot 'just check' a key for a caller (which kills a whole social-engineering genre); and key hygiene becomes procedural — record the key in your own secret manager at creation, because the product will never show it again.
Rotation is the natural companion habit: create the new key, deploy it, verify calls attribute correctly, revoke the old. Because list and revoke are first-class operations on both surfaces, rotation is a five-minute procedure rather than a support ticket. Schedule it like certificate renewal — and immediately, without ceremony, whenever a team member with key access leaves or a secret might have been logged.
The usage endpoint: metering you can see
The /api/v1/usage endpoint reports a key's consumption — the metered reality behind plan limits such as eval runs (100/month on Pro, 1,000 on Team). Its existence changes the operator's relationship to limits: instead of discovering a cap by collision, you can watch consumption approach it, attribute spikes to the change or experiment that caused them, and make the tier conversation an arithmetic one (see the runs guide).
Wire a lightweight check on usage into your release routine: before a big testing day, glance at the month's consumption; after an incident, confirm nothing in the response burned the budget you need for verification runs. Metering you can see is metering you can govern.
Key hygiene for small teams
Small teams leak keys in predictable places: committed to a repo 'temporarily', pasted into a chat, baked into a client-side bundle (the runtime must be called from your backend — a browser-visible key is a published key), or shared as one key across every bot and environment, which destroys attribution and makes revocation an outage. The countermeasures are equally predictable and cheap: one key per bot per environment, secrets in a manager, .gitignore discipline plus a pre-commit scan, and revocation as the reflexive answer to any doubt.
When in doubt, revoke: the cost of an unnecessary revocation is a five-minute rotation; the cost of a necessary one delayed is your bot's safety record attributed to someone else's calls. The product's design — hashes, resolver, usage visibility — is built to make the safe action the easy action. Take the hint.
Five actions for clean key practice
- Create one key per bot per environment through the bot-owner surface, and store each in your secret manager at creation — it will never be shown again.
- Confirm runtime and metrics calls originate from your backend only; no CompanionGuard key may ever ship in client-side code.
- Add the usage endpoint to your release routine: check monthly consumption before big testing days and after incidents.
- Rehearse rotation once — create, deploy, verify attribution, revoke — so the real rotation under pressure is a procedure, not an improvisation.
- Revoke on any doubt (departed team member, possible log exposure, shared-too-widely key) and treat the five-minute rotation as the cheap option it is.
Worked example: a leaked key, a ten-minute ending
A fictional builder, Ash, finds their bot's API key in a public gist — pasted by a contractor into a debugging snippet weeks earlier. Because the key's scope is one bot and one environment, the blast radius is bounded by design. Ash creates a replacement key in the bot-owner surface, deploys it to the backend, verifies via the usage endpoint that calls now attribute to the new key, and revokes the leaked one — total elapsed time, about ten minutes, most of it deploy lag.
The post-incident note is one paragraph: no evidence entries were attributable to foreign calls in the window (the chain's per-bot attribution made the audit a filter, not a forensic project), and the contractor's access procedure changes to issued-per-person keys so future revocations are surgical. The story is invented; the surfaces, resolver and hash-only storage are the product's own.
Frequently asked questions
Who can create API keys?
Both the platform owner (owner surface) and a bot's owner (bot-owner surface) can create, list and revoke keys. A resolver ties a presented key to its bot so runtime and metrics calls attribute correctly.
Can a lost API key be recovered?
No — keys are stored only as hashes, as license keys are. The recovery path is revocation and reissue: create a new key, deploy it, verify attribution, revoke the old one.
What does /api/v1/usage show?
The key's consumption against the metered surfaces — the visibility behind plan limits such as eval runs (100/month Pro, 1,000 Team) — so operators can govern usage instead of discovering caps by collision.
May I call the runtime from the browser with my key?
No. Keys authenticate backend-to-backend calls; a key shipped in client-side code is a published key. Runtime integration belongs in your server code, per session event.
What should I do if a key leaks?
Revoke it immediately from the key surface, issue and deploy a replacement, and verify attribution on the usage endpoint. Bounded scope (one key per bot per environment) keeps the incident small.
Keep going
Related guides: Integrating the Crisis Evidence Runtime: Start, Message, End — and What to Do with Each Answer · Eval Run Budgeting: 100 a Month on Pro, 1,000 on Team — Who Needs What · Audit Logs for Companion Bots: Keep Decisions, Not Conversations
Put it to work: Create the free kit · Eval harness · Scenario tests · Crisis runtime · Disclosure packs · Pricing · All CompanionGuard guides