Credentials

Use the credential endpoints to award a custom credential from your own systems, for example when someone finishes a program you track elsewhere, and to show which credentials an account issues, which ones a person holds and which are waiting to be claimed. Creating, editing, minting and deploying credentials, and claiming one, stay in the Hive3 app: an award notifies the person, who then claims the credential there.

JavaScript and Python follow the same request pattern as the tabbed examples; the cards that show only curl are trivial to translate.

#Scopes, plan and targeting

No other scope implies these; keys created before they existed need to be replaced (scopes). API access needs Honey Bee or above (overview).

The list route acts on the key owner's own account unless you add ?account=<account ID or @handle>. The API calls an account that others join a community, so for another account the key also needs communities:read (reads) or communities:write (writes), must include that account when the key is limited to selected accounts, and the key owner must currently be an owner, admin or moderator of it. Routes that take a credential ID use the account that owns the credential and ignore ?account=. See managed accounts.

POST /api/v1/credentials/{credentialId}/awards is limited per awarding account to 30 requests per minute and 500 people per day. The budget is shared with the Hive3 app and counts every handle you send, including people who already hold the award. It sits on top of the account-wide budget (rate limits). Over a limit returns 429 rate_limited with a Retry-After header.

#The credential object

#Read credentials an account issues

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

{
  "data": [{
    "id": "credential_123", "accountId": "account_123", "name": "Mentor", "description": "Helped five members ship", "imageUrl": "https://example.com/mentor.png",
    "attachmentType": "general", "attachmentId": null, "claimAccess": "awarded", "maxSupply": null, "deployStatus": "confirmed", "chainName": "Base",
    "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:00:00.000Z"
  }],
  "page": { "nextCursor": null, "hasMore": false }
}

curl https://app.hive3.tech/api/v1/credentials/credential_123 \
  -H "Authorization: Bearer $HIVE_API_KEY"

#Award a credential

curl -X POST https://app.hive3.tech/api/v1/credentials/credential_123/awards \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handles":["@ada","grace","nobody"]}'

const res = await fetch("https://app.hive3.tech/api/v1/credentials/credential_123/awards", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.HIVE_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ handles: ["@ada", "grace", "nobody"] }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://app.hive3.tech/api/v1/credentials/credential_123/awards",
    headers={"Authorization": "Bearer " + os.environ["HIVE_API_KEY"]},
    json={"handles": ["@ada", "grace", "nobody"]},
)
data = res.json()["data"]

{ "data": { "awarded": 2, "notFound": ["nobody"] } }

#Read your own credentials

curl "https://app.hive3.tech/api/v1/credentials/mine" \
  -H "Authorization: Bearer $HIVE_API_KEY"

{
  "data": [{
    "id": "claim_123", "credentialId": "credential_123", "status": "confirmed", "chainName": "Base", "claimedAt": "2026-10-28T09:00:00.000Z",
    "credential": { "id": "credential_123", "accountId": "account_123", "name": "Mentor", "description": "Helped five members ship", "imageUrl": "https://example.com/mentor.png", "attachmentType": "general", "attachmentId": null, "claimAccess": "awarded", "maxSupply": null, "deployStatus": "confirmed", "chainName": "Base", "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:00:00.000Z" }
  }],
  "page": { "nextCursor": null, "hasMore": false }
}

curl "https://app.hive3.tech/api/v1/credentials/claimable?limit=10" \
  -H "Authorization: Bearer $HIVE_API_KEY"

{
  "data": [{
    "id": "credential_123", "accountId": "account_123", "name": "Mentor", "description": "Helped five members ship", "imageUrl": "https://example.com/mentor.png",
    "attachmentType": "general", "attachmentId": null, "claimAccess": "awarded", "maxSupply": null, "deployStatus": "confirmed", "chainName": "Base",
    "createdAt": "2026-10-27T18:00:00.000Z", "updatedAt": "2026-10-27T18:00:00.000Z", "awardedAt": "2026-10-27T18:30:00.000Z"
  }],
  "page": { "nextCursor": null, "hasMore": false }
}

#Award a credential end to end

1. Find the credential

   Call GET /api/v1/credentials (add ?account= for a community you help run) and pick a credential whose attachmentType is general. Keep its id.

2. Award it

   Call POST /api/v1/credentials/{credentialId}/awards with up to 50 handles. Keep the response's notFound list.

3. Handle misses and retries

   Fix or drop the handles in notFound and send only those again. Sending the full list again is safe: people who already hold the award are skipped and not notified twice.

4. Confirm with the recipient

   When the recipient's own key calls GET /api/v1/credentials/claimable, the credential is listed until they claim it in the app. After that it appears in GET /api/v1/credentials/mine.