Authentication
The API takes two bearer credentials: an API key, a workspace's server-to-server credential for the inference API and the SDKs, and a person's access token, issued to the person's own tools by sign-in. Use a key for a server or an SDK; hi and HIPS Code sign in. Every request is attributed to one workspace and one plan; the plan decides limits and which requirements are allowed.
Parts list: Authentication
CredentialAuthorization: Bearerfollowed by the key. Created in the Console's API keys view, named, of a kind, shown once, stored as a hash. Public idkey_. The key's value is read fromHIPS_API_KEY; no key value appears on any page.Where keys liveOn the server or in a secret store. Keep keys on the server or in an appropriate secret store, rather than shipping them in a public browser application. The gateway sends no cross-origin headers for live keys Not decided yet.
Publishable keysReserved for a later browser path and not part of this version of the contract Not decided yet.
A person's toolsThe
hiCLI, the provider app and HIPS Code need no API key: they sign in as the person with OAuth 2.0 device authorization. The tool shows a user codeXXXX-XXXXand its link, the person approves it in the Console while signed in and chooses the workspace, and the tool receives a short-lived, scoped access token with a refresh token. The gateway accepts that token as the bearer beside API keys and attributes usage to the chosen workspace. The access token lasts 1 hour and the refresh token 30 days, replaced on each use; an expired access token answers 401token_expired, and a token without theinferencescope 403insufficient_scope. The steps are on Sign in with device authorization.Key defaultsEach key carries defaults for the four request requirements (pool, pricing mode, region, fallback), set in the Console.
Key kindfullorinference_onlyFixed at creation. Both reach every route of the API: chat completions, Responses, Messages, models, embeddings, rerank, tasks, and uploads, files and batches where they are offered. A
fullkey reads and deletes every upload, file and batch of its workspace; aninference_onlykey, like a person's token, only those it created. Writing a knowledge base's documents needs afullkey or a person whose role writes, once Knowledge is switched on. A route the kind excludes is a 403key_scope_denied. Which models a key may name is set with an access guardrail assigned to the key.Workspace stateA key of a paused or deleted workspace answers 403
workspace_suspendedon every route; a key of a workspace whose owner cannot use HIPS answers 403permission_errorwith the codeaccount_restricted. While identity verification is on, a key of a workspace whose owner has not passed it answers 403permission_errorwith the codeworkspace_unverified; identity verification is switched off since 2026-11-09, so that code is not sent now.
| Status | Type | Code | Situation | Retry |
|---|---|---|---|---|
| 401 | authentication_error | missing_api_key | No Authorization header, or not a bearer (on Messages, no x-api-key either) | No |
| 401 | authentication_error | invalid_api_key | Unknown, malformed or revoked key or person's token; on Messages, x-api-key and Authorization carrying different values. The message never says which | No |
| 401 | authentication_error | token_expired | A person's access token past its life; the tool refreshes it and sends the request again | After the refresh |
| 403 | permission_error | key_scope_denied | The key's kind excludes the route: a retrieval key on any route but its batch and file reads; a key other than full writing a knowledge base's documents | No |
| 403 | permission_error | insufficient_scope | A person's access token without the inference scope | No; sign the tool in with the scope |
| 403 | permission_error | workspace_unverified | The workspace's owner has not passed identity verification; the message names the Console's verification screen. Not sent while identity verification is switched off, as it is since 2026-11-09; documented for when it is switched back on | After verification |
| 403 | permission_error | member_unverified | A person's access token whose person has not passed identity verification. Not sent while identity verification is switched off, as it is since 2026-11-09; documented for when it is switched back on | After verification |
| 403 | permission_error | account_restricted | The workspace's owner, or the person a token belongs to, cannot use HIPS. The message says to contact HIPS support | No; contact support |
| 403 | workspace_suspended | workspace_paused | The workspace is paused: by balance, by an administrator, by a dispute, by a budget hard stop or by an owner. The message says where to resolve it | After resolution |
| 403 | workspace_suspended | plan_lapsed | A lapse no longer pauses a workspace: a lapsed or canceled paid plan, or an ended plan grant, moves it to the free plan at once. Only a workspace a lapse paused before then answers this, until the platform moves it to the free plan within about a minute | After about a minute |
| 403 | workspace_suspended | workspace_deleted | The workspace is deleted (restorable 30 days) | After restore |
- Status
- 401
- Type
authentication_error- Code
missing_api_key- Situation
- No
Authorizationheader, or not a bearer (on Messages, nox-api-keyeither) - Retry
- No
- Status
- 401
- Type
authentication_error- Code
invalid_api_key- Situation
- Unknown, malformed or revoked key or person's token; on Messages,
x-api-keyandAuthorizationcarrying different values. The message never says which - Retry
- No
- Status
- 401
- Type
authentication_error- Code
token_expired- Situation
- A person's access token past its life; the tool refreshes it and sends the request again
- Retry
- After the refresh
- Status
- 403
- Type
permission_error- Code
key_scope_denied- Situation
- The key's kind excludes the route: a retrieval key on any route but its batch and file reads; a key other than
fullwriting a knowledge base's documents - Retry
- No
- Status
- 403
- Type
permission_error- Code
insufficient_scope- Situation
- A person's access token without the
inferencescope - Retry
- No; sign the tool in with the scope
- Status
- 403
- Type
permission_error- Code
workspace_unverified- Situation
- The workspace's owner has not passed identity verification; the message names the Console's verification screen. Not sent while identity verification is switched off, as it is since 2026-11-09; documented for when it is switched back on
- Retry
- After verification
- Status
- 403
- Type
permission_error- Code
member_unverified- Situation
- A person's access token whose person has not passed identity verification. Not sent while identity verification is switched off, as it is since 2026-11-09; documented for when it is switched back on
- Retry
- After verification
- Status
- 403
- Type
permission_error- Code
account_restricted- Situation
- The workspace's owner, or the person a token belongs to, cannot use HIPS. The message says to contact HIPS support
- Retry
- No; contact support
- Status
- 403
- Type
workspace_suspended- Code
workspace_paused- Situation
- The workspace is paused: by balance, by an administrator, by a dispute, by a budget hard stop or by an owner. The message says where to resolve it
- Retry
- After resolution
- Status
- 403
- Type
workspace_suspended- Code
plan_lapsed- Situation
- A lapse no longer pauses a workspace: a lapsed or canceled paid plan, or an ended plan grant, moves it to the free plan at once. Only a workspace a lapse paused before then answers this, until the platform moves it to the free plan within about a minute
- Retry
- After about a minute
- Status
- 403
- Type
workspace_suspended- Code
workspace_deleted- Situation
- The workspace is deleted (restorable 30 days)
- Retry
- After restore
Related sheets
- Sheet
- 18 of 20
- Detail
- A
- Updated
- 2026-11-14