Authentication

The HASP AI API authenticates every request via a Bearer token — no OAuth flow, no session cookies. Three credential types share the Authorization: Bearer <token> mechanism but serve different callers:

Prefix	Credential	Who holds it
`hasp_api_live_*`	Personal access token (API key)	A human or service integrating directly — the credential this page is mostly about.
`hasp_agt_live_*`	Agent credential	An AI agent acting with a human’s delegated authority. See Agents overview.
`hasp_pat_live_*`	Developer credential	Issued via the `hasp` CLI / OAuth device or PKCE flow for tooling like coding agents. See OAuth Quickstart.

Each type also has a _test_ variant (see Test keys below). The token’s prefix is what routes a request to the right auth guard — mixing them up (e.g. sending an agent credential where an API key is expected) fails authentication rather than silently working.

API key format

hasp_api_live_<32 Crockford base32 characters>

Keys are issued with the prefix hasp_api_live_ and are globally unique. The 32-character body uses the Crockford base32 alphabet (ambiguous lookalike characters 0, O, 1, l, I excluded). The full token is shown exactly once on creation. HASP stores only a SHA-256 hash — if you lose the token, revoke it and issue a new one. A key can optionally be given an expiry (expires_at, an ISO 8601 timestamp in the future) when it is created. A key without expires_at never expires. After expires_at the key is rejected with INVALID_API_KEY.

Sending the token

Pass the key in the Authorization header on every request:

Authorization: Bearer hasp_api_live_your_key_here

The Anthropic-compat endpoints (POST /v1/messages and POST /v1/messages/count_tokens) also accept the key in the x-api-key header — the header the Anthropic SDKs and Anthropic-native coding agents send when configured with an API key. If both headers are present, Authorization wins. Every other endpoint accepts only Authorization: Bearer.

Test keys

Every key is minted in either live or test mode, distinguished by prefix: hasp_api_live_* vs hasp_api_test_*. Test-mode keys are for development against the real API without touching production billing:

Requests draw from a separate sandbox token allotment (per your API tier), not your org’s regular AI credit balance.
Exceeding the allotment, or having no active API subscription / Free Evaluation, returns 402 sandbox_allotment_exhausted rather than the regular CONSUMPTION_BLOCKED credit error.
Everything else — scopes, BAA requirement, PHI handling, rate limits — behaves identically to a live key. Test mode changes billing, not behavior.

Agent and developer credentials do not have a meaningful test mode distinction of their own — isTestMode() is always false for those caller types; only personal access tokens draw from the sandbox allotment.

Agent credentials

An agent credential (hasp_agt_live_*) is a delegated, scope-constrained credential an AI agent uses to act on a human’s behalf — distinct from a personal API key a human or service holds directly. Agent credentials carry their own rate limits, concurrency caps, and delegation-chain-depth limits independent of the parent key (see the (Agent SDK) codes in the Error Reference). Full lifecycle — registering an agent, issuing a credential, granting scopes, revocation — is covered in Agents overview.

Device authorization

If you’re integrating via the hasp CLI on a machine with no browser (SSH, containers), authenticate with the RFC 8628 device authorization grant instead of the standard browser redirect flow. See Device Authorization.

Scopes

Every API key has one or more scopes, assigned at creation and immutable after (issue a new key to change them). A request to a route protected by a scope the key does not have returns 403 MISSING_SCOPE. Scope grants are additive — a key with multiple scopes gets the union of what each grants.

Scope	Grants access to
`ai:chat`	`POST /v1/ai/chat`, `POST /v1/messages`, `POST /v1/messages/count_tokens`, `POST /v1/chat/completions`
`ai:documents`	`POST /v1/files`, `GET /v1/files`, `GET /v1/files/{id}`, `GET /v1/files/{id}/content`, `DELETE /v1/files/{id}`
`ai:embeddings`	`POST /v1/knowledge` (upload) and `DELETE /v1/knowledge/{document}` — the writes that change the embedded knowledge index
`knowledge:read`	`GET /v1/knowledge`, `GET /v1/knowledge/{document}`, and the `knowledge.search` tool call
`control:read`	Read access across the control plane: API keys, agents, audit, budget, models, personas, projects, records, schemas, workflows, and settings. Does not include webhook or integration reads (see below).
`control:webhooks`	Full webhook management: `GET`/`POST /v1/webhooks`, `PATCH`/`DELETE /v1/webhooks/{id}`, secret rotation, deliveries, and event types.
`control:integrations`	Full Integrations (BYO-Tool) management: `GET`/`POST /v1/integrations`, secret rotation, deletion, and binding management under `/v1/integrations/{id}/bindings`.
`control:author`	Write access to projects, schemas (entities/fields), and workflow authoring/publishing — the “build” half of the control plane, as opposed to `control:read`’s “view” half.
`control:workflows`	Trigger and read workflow runs (`workflow.run` + `workflow.read`) without granting authoring access — for integrations that only need to kick off an existing workflow.
`org.end_users.read`	`GET /v1/orgs/{organization}/end-users/{runtimeUser}/export`

Assign only the scopes a key needs. A key used for chat-only integrations should carry only ai:chat. Developer credentials (hasp_pat_live_*) use their own two-scope vocabulary: inference:write grants the same inference endpoints as ai:chat; inference:read grants no capability-gated endpoint on its own. A developer credential has no control-plane or file-upload access.

Creating keys

Via the dashboard: API → Keys → Create Key (/developers/keys/new). Via the API (requires a key with a scope granting Capability::ApiKeyWrite — currently control:read):

curl -X POST https://api.usehasp.com/v1/api_keys \
  -H "Authorization: Bearer hasp_api_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-chat-service",
    "scopes": ["ai:chat"]
  }'

See Control: API Keys for the full endpoint reference.

BAA requirement

All requests additionally require an active Business Associate Agreement (BAA) on your organization. If your org has no active BAA, every request — regardless of key validity — returns:

{
  "success": false,
  "error": {
    "code": "BAA_REQUIRED",
    "type": "payment_required",
    "message": "An active Business Associate Agreement is required to use the AI API.",
    "retryable": false,
    "request_id": "req_..."
  }
}

Sign the BAA in Settings → Compliance → Business Associate Agreement.

Error responses

Code	HTTP	Meaning
`INVALID_API_KEY`	401	Token not found, malformed, revoked, or past its `expires_at`
`BAA_REQUIRED`	402	No active BAA on the org
`MISSING_SCOPE`	403	Key exists but lacks the required scope

Agent and developer credentials have their own authentication error codes (AGENT_CREDENTIAL_NOT_FOUND, DEVELOPER_CREDENTIAL_REVOKED, etc.) — see the full Error Reference.

Data API

The Data API (https://{org}.usehasp.run/api/hasp/v1/projects/{project}/…) reads and writes an app’s records. It is a separate surface from the AI API, with its own credentials — an AI API key (hasp_api_*) does not authenticate it. A request is authenticated by one of:

Prefix / mechanism	Credential	Scope
Runtime session cookie (`hasp-runtime-session`)	The signed-in user, when the app itself calls the API from the browser — what the JS SDK does	The user’s role in the app.
`hasp_pak_live_`, `hasp_pak_test_`	Project API key, sent as `Authorization: Bearer …`	The project it was issued for — or, for a customer-scoped key, every project in that customer’s set. Keys can carry an IP allowlist; a request from another address fails with `IP_NOT_ALLOWED`. Revoked or expired keys fail with `API_KEY_REVOKED` / `API_KEY_EXPIRED`. Created by a project admin under the project’s API keys page — see Creating a project API key.
`hasp_agt_live_`, `hasp_agt_test_`	Agent credential, sent as `Authorization: Bearer …`	The projects its authorization grants name; every request is additionally pinned to the project in the URL.
none, with an `X-Hasp-AppId` header	Anonymous	Reads (`GET …/records`, `GET …/records/{id}`) when the header names a published app of this project whose access mode is `public`; and form submissions to `POST …/records/anonymous` when the header names a published app of this project whose audience is public and which allows anonymous submission. Nothing else.

When several are present, the session is checked first, then the bearer token. Writes pass the same BAA gate as the AI API — see BAA requirement. Errors use the same envelope and codes as the AI API — see Error responses.

AI Studio

Platform

AI API

Data API

App Builder SDK

Authentication

API key format

Sending the token

Test keys

Agent credentials

Device authorization

Scopes

Creating keys

BAA requirement

Error responses

Data API

​API key format

​Sending the token

​Test keys

​Agent credentials

​Device authorization

​Scopes

​Creating keys

​BAA requirement

​Error responses

​Data API

API key format

Sending the token

Test keys

Agent credentials

Device authorization

Scopes

Creating keys

BAA requirement

Error responses

Data API