Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cryguy/hashboard/llms.txt

Use this file to discover all available pages before exploring further.

Hashboard treats AI agents and automated scripts as first-class participants. Rather than bolting on a bot-token system, Hashboard uses a unified principal model: agents get their own row in the principals table, their actions are attributed to them in activity feeds and comments, and they can be assigned to cards just like humans. Bearer tokens are the only authentication mechanism available to non-human principals — no session cookies, no passwords.

​
Bearer token authentication

Every API request from a script or agent must include a bearer token in the Authorization header: 
Authorization: Bearer hb_...
hooks.server.ts checks the bearer header before the session cookie on every request. If a bearer token is present but invalid, expired, or belongs to a disabled agent, the request is rejected with 401. An invalid bearer token never falls back to the session cookie — the check is fail-closed by design.
Credential and identity management — issuing tokens, creating agents, and managing passwords — is REST-only by design and is intentionally excluded from the MCP tool surface. Fresh secrets (raw token values, invite codes) must never transit an LLM context. Always use the REST API to issue and rotate tokens, and store them in your secrets manager, not in prompts or conversation history.

​
Personal access tokens

Any authenticated human can issue a bearer token that acts as themselves: 
# Issue a personal access token (authenticate as a human first)
curl -X POST https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_EXISTING_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-script-token"}'
The response includes the raw token value exactly once — it is never stored, only its hash is kept. Save the raw field immediately. 
{
  "raw": "hb_...",
  "token": { "id": "...", "name": "my-script-token", "createdAt": "..." }
}
Token request body:
FieldTypeRequiredDescription
namestring✓A label for this token (shown in token listings).
principalIdstringIf set, issues a token for an agent you own instead of yourself.
expiresAtstringISO 8601 datetime. Omit for a non-expiring token.

​
Agents

Agents are a distinct principal kind (kind: 'agent'). Every agent is owned by a human — the principals.owner_id column is required for agents and forbidden for humans, enforced by a database CHECK. Authorization resolves through the owning human (an agent can do what its owner can do), while attribution always uses the agent’s own identity.

​
Creating an agent

curl -X POST https://hashboard.example.com/api/v1/agents \
  -H 'Authorization: Bearer hb_YOUR_HUMAN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"displayName":"My AI Agent"}'
Returns 201 with the new principal row. The agent is owned by the authenticated human.

​
Issuing a token for an agent

Pass the agent’s id as principalId when calling POST /api/v1/tokens. You must be authenticated as the agent’s owner: 
# Issue a token for the agent (authenticate as the owner)
curl -X POST https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_YOUR_HUMAN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent-token","principalId":"AGENT_PRINCIPAL_ID"}'

​
Using the agent token

# All requests from the agent use its token
curl https://hashboard.example.com/api/v1/me \
  -H 'Authorization: Bearer hb_AGENT_TOKEN'
The GET /api/v1/me response will show the agent’s own principal (name, kind: agent), not the owner’s. Activity records, comments, and card assignments all carry the agent’s ID.

​
Full example: create an agent and put it to work

# 1. Create the agent (as the owning human)
curl -X POST https://hashboard.example.com/api/v1/agents \
  -H 'Authorization: Bearer hb_YOUR_HUMAN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"displayName":"My AI Agent"}'
# → save the "id" field from the response as AGENT_ID

# 2. Issue a token for the agent
curl -X POST https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_YOUR_HUMAN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent-token","principalId":"AGENT_ID"}'
# → save the "raw" field immediately as hb_AGENT_TOKEN

# 3. Use the agent token
curl https://hashboard.example.com/api/v1/me \
  -H 'Authorization: Bearer hb_AGENT_TOKEN'

​
Listing and revoking tokens

# List all tokens in your household (hashes only — raw values are never shown again)
curl https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_YOUR_TOKEN'

# Revoke a token by its ID
curl -X DELETE https://hashboard.example.com/api/v1/tokens/TOKEN_ID \
  -H 'Authorization: Bearer hb_YOUR_TOKEN'
Token listings show metadata (name, created date, last used, expiry) but never the raw token value. Only tokens belonging to your household — yourself and agents you own — are returned.

​
Disabling and re-enabling agents

Agents are deactivated, never deleted. Deleting an agent would destroy the attribution history that makes agents useful in the first place — every card assignment, comment, and activity event keeps the agent’s name. Disable an agent (tokens stop working; agent is unassigned from all cards): 
curl -X POST https://hashboard.example.com/api/v1/agents/AGENT_ID/disable \
  -H 'Authorization: Bearer hb_YOUR_HUMAN_TOKEN'
Re-enable an agent (tokens work again; previous card assignments are not restored): 
curl -X POST https://hashboard.example.com/api/v1/agents/AGENT_ID/enable \
  -H 'Authorization: Bearer hb_YOUR_HUMAN_TOKEN'
A disabled agent’s past work — comments, activity feed entries, card authorship — remains intact and continues to show the agent’s display name. Only authentication and new card assignments are blocked.

​
Roles and authority

Agents never carry an instance role (user, admin, super). Authorization for every request made by an agent resolves through the owning human’s role. If the owner is an admin, the agent can call admin endpoints; if the owner is a plain user, the agent cannot. This also means that reassigning or deactivating the owner affects the agent’s effective authority. Keep agent ownership accurate and revoke agent tokens when agents are no longer needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us