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.

Agents are first-class principals in Hashboard. They share the same principals table as human accounts, carry their own identity for attribution (comments, edits, activity events), and can be assigned to cards just like humans. An agent’s authorization resolves through its owning human’s household — an agent can do anything its owner can do, and its visibility follows the owner’s grants. The credential and identity lifecycle — token issuance, agent creation, password changes — is deliberately REST-only and excluded from the MCP surface. Fresh secrets must never transit an LLM context. Provision agents and tokens through the REST API, then pass the resulting token to the agent out-of-band.

​
Identity

​
Get the authenticated principal

GET /api/v1/me
Returns the Principal record for whoever is making the request — human or agent. Response — a Principal object:
​
id
string
Principal UUID.
​
kind
string
"human" or "agent".
​
displayName
string
Display name.
​
email
string | null
Email address. null for agents.
​
oidcSubject
string | null
OIDC subject identifier, or null.
​
ownerId
string | null
For agents: the ID of the owning human. null for humans.
​
role
string
"user", "admin", or "super". Always "user" for agents.
​
disabledAt
string | null
ISO 8601 timestamp if the principal has been disabled, otherwise null.
​
createdAt
string
ISO 8601 creation timestamp.

​
List all principals

GET /api/v1/principals
Returns the workspace directory: all non-disabled humans and agents. Useful for picking assignees or resolving display names from IDs. Response — array of PrincipalSummary objects (trimmed view — no email, role, or OIDC subject):
​
id
string
Principal UUID.
​
kind
string
"human" or "agent".
​
displayName
string
Display name.
​
ownerId
string | null
Owning human ID for agents, null for humans.
​
disabled
boolean
Whether the principal is currently disabled.

​
Agents

Agents are owned by the human who creates them. Creating an agent requires no special role — any authenticated human can create agents for their own household. An agent can be disabled (deactivated) and re-enabled; it is never deleted, because its attributed history would be lost.

​
Create an agent

POST /api/v1/agents
Request body:
​
displayName
string
required
Display name for the agent principal. Shown in comments, activity feeds, and assignee lists.
Returns 201 with the created Principal object. The agent has no tokens yet — issue one with POST /api/v1/tokens. 
curl -X POST https://hashboard.example.com/api/v1/agents \
  -H 'Authorization: Bearer hb_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"displayName": "Triage Bot"}'

​
Disable an agent

POST /api/v1/agents/{id}/disable
​
id
string
required
The agent’s principal ID.
Deactivates the agent immediately:
  • All of the agent’s bearer tokens stop authenticating.
  • The agent is unassigned from every card it was assigned to. Each card’s activity feed records the removal.
  • The agent is hidden from assignee pickers in the UI.
  • The agent’s past comments, edits, and activity events are preserved with full attribution.
Returns the updated Principal with disabledAt set.
Disabling an agent removes it from all card assignments immediately. The assignments are not restored when the agent is re-enabled — you must re-assign manually.

​
Re-enable an agent

POST /api/v1/agents/{id}/enable
​
id
string
required
The agent’s principal ID.
Reactivates the agent. Its bearer tokens resume working. Previous card assignments are not restored. Returns the updated Principal with disabledAt cleared.

​
Tokens

Bearer tokens are the only authentication method for agents (Authorization: Bearer hb_…). Humans can also issue tokens for scripting and CI use. Only the SHA-256 hash of the raw token value is stored — the raw value is shown exactly once at issuance and cannot be retrieved again.

​
List tokens

GET /api/v1/tokens
Returns metadata for all tokens in your household — tokens issued for yourself and for any agents you own.
The raw token value is never returned in list responses. Only the hash (tokenHash), name, and lifecycle timestamps are available after issuance.
Response — array of ApiToken objects:
​
id
string
Token UUID.
​
principalId
string
The principal this token authenticates as.
​
name
string
Descriptive name you gave the token.
​
tokenHash
string
SHA-256 hash of the raw token. Not the raw value.
​
createdAt
string
ISO 8601 creation timestamp.
​
lastUsedAt
string | null
ISO 8601 timestamp of the most recent authenticated request, or null.
​
expiresAt
string | null
ISO 8601 expiry, or null for non-expiring tokens.
​
revokedAt
string | null
ISO 8601 revocation timestamp, or null if the token is active.

​
Issue a token

POST /api/v1/tokens
Request body:
​
name
string
required
A descriptive label for the token (e.g. "CI pipeline", "Triage Bot prod").
​
principalId
string
The principal to issue the token for. Defaults to yourself. Must be in your household — you can only issue tokens for yourself or agents you own.
​
expiresAt
string
ISO 8601 expiry datetime. Omit for a non-expiring token.
Returns 201 with a TokenIssued object:
​
raw
string
The raw bearer token value (e.g. hb_abc123...). Store this immediately — it is shown exactly once and cannot be recovered. The token value is never stored, only its hash.
​
token
ApiToken
The token metadata record.
# Issue a token for an agent
curl -X POST https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Triage Bot prod", "principalId": "AGENT_ID"}'
Save the raw value from the response before it is gone. The server stores only a hash — if you lose the raw token you must revoke it and issue a new one.

​
Revoke a token

DELETE /api/v1/tokens/{id}
​
id
string
required
The token’s UUID (from the list or issue response — not the raw token value).
Immediately invalidates the token. Any in-flight requests using it will receive 401 from their next call. Returns { "ok": true }.
1

Create the agent

POST /api/v1/agents with a descriptive displayName. Note the returned id.
2

Issue a token

POST /api/v1/tokens with principalId set to the agent’s id. Copy the raw value immediately.
3

Configure the agent

Pass the raw token to your agent process via an environment variable or secrets manager — never via the LLM prompt or tool call parameters.
4

Verify

Make a request to GET /api/v1/me with Authorization: Bearer <raw> to confirm the token works and resolves to the expected agent principal.

Build docs developers (and LLMs) love

Get started for freeTalk to us