Authentication
Send an API key as a bearer token on each GraphQL request:
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.
Personal keys
Open Profile → My API Keys in the organization you want to use. Any enabled member can create and manage their own personal keys there. Give the key a name, select only the permissions it needs, and choose an expiry or Never.
A personal key acts as you within that organization for self-scoped tasks and run visibility. Its effective permissions are the intersection of your current role and the permissions selected for the key. Losing a role permission removes it from the key immediately; a later promotion does not add permissions you never selected. Disabling your membership suspends authentication. Removing membership permanently revokes your personal keys, including if you later rejoin.
Organization keys and administration
Open Organization Settings → Developer → API Keys to create organization keys
and administer all active keys. This requires Manage API keys (canManageApiKeys),
which Owner and Admin roles have and which can be granted to a custom role.
Organization-key creation and permission edits cannot exceed your current grants;
rotation requires holding every grant already on the key. For other members'
personal keys, administrators may list and revoke them; permission changes and
rotation require ownership.
Organization keys carry their explicitly selected permissions independently of the
creator's later role or membership changes. Existing organization keys keep that
behavior.
Both lists show the key type, owner, creation date, expiry, and approximate last-used time. Usage is recorded at most once every five minutes. Not observed means no usage has been recorded since tracking began; it does not prove a key is unused.
Key material, rotation and revocation
The full hbk_… value is shown once, on creation or rotation. Copy it immediately
and store it as a credential; it cannot be retrieved afterwards. The server stores
only its hash and a short display prefix. Choose a name you recognize: task writes
are attributed to the key by name, with owner identity kept separately as provenance.
Rotation replaces the key material and immediately invalidates the old personal credential. Both organization and personal keys invalidate open subscriptions on rotation or revocation. Revocation permanently stops authentication and hides the key from active lists. Its row and historical audit name are retained, and you can reuse its name for a new active key.
Limits
Keys use the bearer header directly, without a JWT refresh flow. An optional expiry stops authentication at the chosen time. Every key remains scoped to one organization. Even a personal key owned by an Owner has a Custom credential role and cannot manage API keys, create or switch organizations, mint user sessions, or perform person-only chat/consent operations. Organization rename and other Owner/Admin operations require a human session. GraphQL API keys do not yet authorize endpoint-process invocation.
Failure modes
| Situation | What you get |
|---|---|
| Missing, malformed, expired or revoked key | HTTP 401, uniformly |
| Personal owner missing, disabled or no longer a member | HTTP 401, uniformly |
| Valid key, but missing the permission for that operation | HTTP 200 with the field null and a PERMISSION_DENIED error entry |
Always inspect the errors array, not just the HTTP status. See Errors.
API-key WebSocket operations revalidate credential validity; personal keys also
revalidate their owner's current enabled membership and role. Subscription delivery
stops if the original credential or the grants that authorized that subscription
are no longer valid; reconnect and start a new operation after permissions change.