Authentication

Parts list: Authentication

1. 01
   Credential

   Authorization: Bearer followed by the key. Created in the Console's API keys view, named, of a kind, shown once, stored as a hash. Public id key_. The key's value is read from HIPS_API_KEY; no key value appears on any page.

2. 02
   Where keys live

   On 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.

3. 03
   Publishable keys

   Reserved for a later browser path and not part of this version of the contract Not decided yet.

4. 04
   A person's tools

   The hi CLI, 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 code XXXX-XXXX and 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 401 token_expired, and a token without the inference scope 403 insufficient_scope. The steps are on Sign in with device authorization.

5. 05
   Key defaults

   Each key carries defaults for the four request requirements (pool, pricing mode, region, fallback), set in the Console.

6. 06
   Key kindfull or inference_only

   full reaches every route; inference_only the inference routes alone (chat completions, responses, models, tasks, jobs, uploads and the jobs it created). Fixed at creation. A route the kind excludes is a 403 key_scope_denied. A per-key model or deployment allow-list is open Not decided yet.

7. 07
   Workspace state

   A key of a paused or deleted workspace answers 403 workspace_suspended on every route; a key of a workspace whose owner has not passed identity verification answers 403 permission_error with the code workspace_unverified.

• Status

  401

  Type

  authentication_error

  Code

  missing_api_key

  Situation

  No Authorization header, or not a bearer

  Retry

  No

• Status

  401

  Type

  authentication_error

  Code

  invalid_api_key

  Situation

  Unknown, malformed or revoked key. The message never says which

  Retry

  No

• Status

  403

  Type

  permission_error

  Code

  key_scope_denied

  Situation

  The key's kind excludes the route

  Retry

  No

• 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

  Retry

  After verification

• 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 which and where to resolve it

  Retry

  After resolution

• Status

  403

  Type

  workspace_suspended

  Code

  plan_lapsed

  Situation

  The subscription lapsed and no owner has yet acknowledged the free plan's request-data policy or paid; the policies hold meanwhile

  Retry

  After acknowledgment or payment

• Status

  403

  Type

  workspace_suspended

  Code

  workspace_deleted

  Situation

  The workspace is deleted (restorable 30 days)

  Retry

  After restore