Authentication
API keys identify your account, decide what each request may do, and can be revoked at any time.
Send the key as a bearer token
Every request to https://developer.council.health/v1 carries an API key in the Authorization header.
OpenAI SDKs set this header from the api_key you pass.
Authorization: Bearer cai_live_...Live and test keys
Live keys start with cai_live_ and test keys with cai_test_. Use test keys for development
and continuous integration so they can be revoked without touching production. Both kinds draw from your account balance.
Scopes
Each key carries only the scopes you choose when you create it. A request that needs a scope the key lacks fails with
403 insufficient_scope.
| Scope | Allows | Endpoints |
|---|---|---|
chat:completions | Create chat completions and list models. | POST /v1/chat/completionsGET /v1/models |
kb:search | Search knowledge bases directly. | POST /v1/kb/search |
kb:documents:write | Upload documents to the knowledge base. | POST /v1/kb/documents |
kb:documents:read | Check document processing jobs. | GET /v1/kb/jobs/{job_id} |
billing:read | Read the balance and pricing. | GET /v1/billing/creditsGET /v1/billing/checkout-config |
billing:write | Start checkout sessions that add funds. | POST /v1/billing/checkout-sessions |
Knowledge scopes
Keys also list the knowledge bases they may read: public_kb for curated public medical knowledge,
customer_kb for documents your account uploads, and personal_kb for documents tied to one person.
Asking for a knowledge scope the key does not allow fails with 403 insufficient_scope.
Model access
A key can be limited to a list of models. Without a list, it can call the default model. Asking for any other model
fails with 400 invalid_request.
When authentication fails
401 missing_api_key: the header is missing or is not a bearer token.403 invalid_api_key: the key is malformed, unknown, revoked, or expired.403 insufficient_scope: the key lacks the scope or knowledge scope the request needs.
Keep keys safe
- Call the API from your server. Keys in browser or mobile code can be read by anyone.
- Give each service its own key so you can revoke one without affecting the others.
- Revoke a key from the API keys page as soon as you suspect it leaked. Requests that use it fail at once.