API keys

Create, check, rotate and revoke the sk_ API keys that authenticate every request, and what each failure looks like.

Every /v1 request authenticates with an API key sent as a bearer token:

Authorization: Bearer sk_…

Keys are managed in the app at app.helping.io, under Settings → API Keys, not through /v1. Owners and admins of the organization can create, rotate and revoke keys; members cannot open the page.

Create a key

Open Settings → API Keys.
Under Create a key, enter a Name of at least three characters that says which integration will use it, then select Create key.
Copy the secret with Copy. It starts with sk_ and is shown once: it cannot be recovered after you select Dismiss or leave the page.
Store it where your code reads it, for example:
Terminal window
```
export HELPINGIO_API_KEY="sk_…"
```

The key is issued to you and belongs to your organization. Spend is attributed per key, so give each integration its own.

Check a key

Listing models proves a key works without running a model, so it costs nothing and is not rate limited.

curl https://api.helping.io/v1/models \
  -H "Authorization: Bearer $HELPINGIO_API_KEY"

A working key answers 200 with the list of models. A key the API does not accept, because it is mistyped, incomplete or revoked, answers 401:

{
  "error": {
    "message": "invalid API key",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

A request with no Authorization header, or one that is not Bearer followed by a key, gets the same 401 with the message missing or malformed Authorization header.

Rotate a key

Rotating a key gives it a new secret. The key keeps its name, its spend history and its conversations.

Open Settings → API Keys and find the key in the list.
Open the key’s actions menu and select Rotate.
Under Keep the current secret working for, choose Stop it now, 1 hour, 24 hours or 7 days. A grace period lets your clients switch to the new secret without downtime.
Select Rotate key, then copy the new secret. It is shown once.

Revoke a key

Revoking a key stops it immediately and cannot be undone. Its spend history stays visible in the app, and conversations it started can no longer be continued by anyone.

Open Settings → API Keys and find the key in the list.
Open the key’s actions menu and select Revoke.
Select Revoke key to confirm.

Keys do not expire on a schedule; revoke or rotate them instead.

Conversation ownership

A conversation is bound to the API key that started it. Only that key can continue, retrieve, or delete it, and a different key in the same organization gets the same 404 as an unknown id. Plan for this when you have several keys: the key that starts a conversation is the key that must finish it.

Authentication failures

401 invalid_api_key: the header is missing or malformed, or the key is unknown or revoked. Check the key as in Check a key.
403 access_denied: the key is valid but is not entitled to what the request asked for. Ask an administrator of your organization.
503 auth_unavailable: the key could not be validated for a moment. It comes with Retry-After: 1, never as a 401, and the SDKs retry 503 automatically, so a short outage never looks like a bad key.