Authentication and API keys

Every API request is authenticated with an API key that belongs to one Hive3 account. The key decides which parts of the API the request can reach (its scopes) and which other accounts it can act on. This page covers creating, scoping, using and retiring keys. The command-line tool creates its own key when you run hive3 login; see CLI sign-in and configuration.

#Who can use API keys

Creating and using API keys is a Honey Bee+ feature.

• Below Honey Bee. If the key owner's account is on Worker Bee, every request with that account's keys returns 403 with the code plan_required and the message API access requires a Honey Bee plan or above. Upgrade the account to use this key again. The keys are kept. They work again when the account returns to Honey Bee or above.
• Account scheduled for deletion. While an account is waiting to be deleted, its keys return 401 with invalid_api_key on every route except the one that cancels the deletion (Export and deletion), which skips the plan check only while the deletion is pending.
• Community-owned keys do not exist. A key always belongs to a person's account. To work on a community, use a key whose owner is an owner, admin or moderator of that community. See Managed accounts.

#Create a key

1. Open the key page

   Go to SettingsHelp & feedbackDeveloper API keysManage API keys. The page is titled API Keys. On a Worker Bee account it shows an upgrade notice instead of the create button.

2. Start a new key

   Select Create API key and enter a Name of up to 80 characters, for example the name of the integration that will use it.

3. Choose account access

   Under Account access pick Read access or Full access. Read access lets the key view your account, posts, resources, broadcasts, tickets, AI assistant and credentials. Full access also lets it change them. The exact scopes are listed under Scopes.

4. Choose community access (optional)

   Expand Community access if the key should work on communities you help run. Pick No access, Read access or Full access, then tick the communities the key may reach. The list shows your own account and each community where you are an owner, admin or moderator, with your role. You must select at least one community when you choose Read or Full access.

5. Copy the key

   Select Create API key. The new key appears once, starting with hive_sk_. Select Copy and store it in a secret manager or an environment variable. The key clears from the screen after two minutes and cannot be shown again. Select Done before you create another key.

Keys created on this page do not expire. Account limits: at most 25 active keys per account, 10 new keys per minute, and 50 new keys per day.

#Send the key

Send the key in the Authorization header on every request. This is the only supported format.

Authorization: Bearer hive_sk_<secret>

export HIVE_API_KEY="hive_sk_..."
curl https://app.hive3.tech/api/v1/me \
  -H "Authorization: Bearer $HIVE_API_KEY"

const res = await fetch("https://app.hive3.tech/api/v1/me", {
  headers: { Authorization: `Bearer ${process.env.HIVE_API_KEY}` },
});
const { data } = await res.json();
console.log(data.person.handle, data.credential.scopes);

import os, requests

res = requests.get(
    "https://app.hive3.tech/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['HIVE_API_KEY']}"},
)
data = res.json()["data"]
print(data["person"]["handle"], data["credential"]["scopes"])

A missing, malformed, revoked, expired or unknown key fails with a 401 before anything else is checked. See Requests, errors and limits for the full error list.

#Scopes

A scope grants access to one area of the API. Each endpoint card in the reference lists the scope it needs. A request whose key lacks the scope returns 403 with the code insufficient_scope and the missing scopes in error.requiredScopes.

No older scope implies the eight newest ones (broadcasts, tickets, ai and credentials, read and write). A key created before they existed cannot reach those areas; create a new key.

Scopes are necessary but not sufficient. Operations on communities also check your current role, and some checks depend on the owning account's plan.

#Presets

The key page and the command-line login bundle scopes into presets.

#Managed accounts

A key can act on an account other than its owner's when the owner is currently an owner, admin or moderator of that account. Most routes take an optional account query parameter, an account ID or handle, to choose the target. Without it, the request acts on the key owner's own account. Posts, events and the other resources use the owner field in the request body instead; see Events, courses, content, quests, jobs.

curl "https://app.hive3.tech/api/v1/profile?account=design-guild" \
  -H "Authorization: Bearer $HIVE_API_KEY"

For any account other than the key owner's, all three checks must pass:

1. Scope. Reads need communities:read and writes need communities:write, in addition to the scope for the area (for example broadcasts:write). Moderation actions need communities:moderate, which communities:write includes. A missing scope returns 403 insufficient_scope.
2. Allowlist. A key created with selected communities can act only on those. Otherwise it returns 403 forbidden with a message such as API key does not include this managed account. A key created with No access reaches only its owner's account. Keys created by hive3 login have no allowlist and reach every account the owner currently helps run.
3. Live role. The owner must hold the required role right now. Role changes take effect on the next request: a demoted admin loses access immediately, even though the key is unchanged. A missing role returns 403 forbidden, for example Your role on this account does not allow this action.

Call GET /api/v1/capabilities to list the accounts the key can act on, with the role and capabilities on each. It needs communities:read.

{
  "data": {
    "person": { "id": "account_123", "handle": "ada", "displayName": "Ada" },
    "credential": { "id": "key_123", "scopes": ["account:read", "communities:read"] },
    "communities": [
      {
        "communityId": "account_456",
        "name": "Design Guild",
        "role": "admin",
        "capabilities": { "canRead": true, "canWrite": true, "canModerate": true }
      }
    ]
  }
}

GET /api/v1/me returns the same object and needs account:read. In both, credential.communityIds is present when the key has an allowlist. An empty communities list means the key has no rights over another account.

#Rotate and revoke keys

On the API Keys page, Active keys lists each key's name, its recognizable prefix (hive_sk_… plus the last four characters), when it was last used, and whether it has Read access or Full access. The filter menu switches to Revoked keys.

• Rotate creates a new key with the same name, scopes and community access, labelled (rotated), and revokes the old key at the same moment. Copy the new key, then update your integration. Rotating counts against the 25-key limit before the old key is removed, so revoke an unused key first if you are at the limit.
• Revoke disables a key immediately. A revoked key returns 401 invalid_api_key.
• A key can revoke itself with DELETE /api/v1/account/keys/current, which needs no scope (details). This is what hive3 logout does.

Revoke any key that may have been exposed, then create a replacement.

#Keep keys safe

• Keep keys in environment variables or a secret manager. Do not commit them to source control, put them in URLs, or paste them into chat or tickets.
• Use the narrowest preset that works: Read access for dashboards and reports, Full access only for integrations that write.
• Give every integration its own key and restrict community access to the communities it needs.
• Rotate keys on a schedule and when a teammate who had access leaves.

#Authentication errors