Authenticate API requests

API requests can use an application session, a verified provider bearer token, or a Helm API token. These credentials have distinct verification rules.

Server integration credentials

A Helm API token is the practical starting point for a server integration. Create it in Settings and send it in the Authorization header:

Authorization: Bearer YOUR_HELM_API_TOKEN
Accept: application/json

Keep the token on your server. A valid token still needs an admitted user and the registered operation’s scope.

Provider bearer tokens additionally require live owned-session verification. A token-looking string is not proof that its session is still accepted.

Browser sessions

Cookie-authenticated unsafe requests require the exact application Origin. Keep Host/protocol validation intact; forwarded headers are not permission to substitute an origin. Bearer credentials do not make cross-origin browser cookie access a supported shortcut.

Authentication routes

Relative to /api/v1, the auth surface includes POST /auth/sign-in, POST /auth/sign-up, GET /auth/session, POST /auth/sign-out, POST /auth/clear-browser-session, PATCH /auth/email, and password/recovery routes. Prefer the first-party UI for password and session management.

Signup returns a neutral response. A success envelope alone does not prove a verified, admitted session. Check the owned session before entering private data flows.

Handle refusal

Treat 401 as missing or rejected credentials and 403 as a permission or boundary refusal. Verification can return 503 when identity cannot be established; do not silently reuse retained private data. Read errors and user session guidance.