Skip to main content

Authentication

Every request is a POST carrying an organization API key as a bearer token.

POST {BASE_URL}/api/graphql
Authorization: Bearer hbk_<key>
Content-Type: application/json

{"query": "...", "variables": {}}

BASE_URL is your organization's server — https://app.honeybase.ai for the hosted product, or http://localhost:8080 when running Honeybase locally.

Creating a key​

Organization Settings → Developer → API Keys.

A key is organization-scoped and carries an explicit permission set chosen at creation time. Grant only the permissions the integration actually needs: permissions are checked per operation, and a key with fewer of them fails loudly rather than silently doing less.

The key is shown once, at creation. Store it the way you store any other credential.

What a key is not​

It is not a JWT. There is no expiry, no refresh dance, no session — you send the same header on every request until the key is revoked.

It also cannot escalate. Regardless of the permissions granted, a key can never:

  • manage API keys (create, list or revoke them),
  • rename or otherwise administer the organization,
  • perform any operation the schema marks Requires Owner or Admin role.

Failure modes​

SituationWhat you get
Missing, malformed, expired or revoked keyHTTP 401, uniformly — the server deliberately does not tell you which
Valid key, but missing the permission for that operationHTTP 200 with the field null and a PERMISSION_DENIED error entry

That second case is the one that trips up client code: a permission failure is a successful HTTP response. Always inspect the errors array, not just the status code. See Errors.

Attribution​

Writes made with a key are attributed to the key by name. A task created through the API shows the key's name in that task's audit trail (tasks { taskUpdates(taskId:) }). You do not need to — and cannot — impersonate a user to get correct attribution.