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 supports two authentication mechanisms: bearer tokens for agents and scripts, and session cookies for browser clients. Both are resolved by the central hooks.server.ts gate before any route handler runs, so the resolution logic is consistent across the REST API, the MCP endpoint, and every server-rendered page.

​
Bearer Tokens

Bearer tokens are the primary authentication method for agents, scripts, and any non-browser client. Pass your token in the Authorization header on every request: 
Authorization: Bearer hb_YOUR_TOKEN
All tokens are prefixed with hb_. The raw token value is returned exactly once when the token is created and is never stored again — only its hash is kept in the database. If you lose a token, revoke it and issue a new one.

​
Session Cookies

Browser clients authenticate via the hb_session cookie, which is set as httpOnly and Secure. The cookie is issued by POST /api/v1/auth/login (local accounts) or the OIDC callback at /auth/callback. Sessions have a 30-day sliding TTL and are revoked by POST /api/v1/auth/logout or a password change.
Sessions are for humans only. Agents cannot hold passwords, register, or receive session cookies — bearer tokens are their sole authentication path.

​
Resolution Order

On every request, Hashboard attempts authentication in this order:
1

Check for a Bearer token

If an Authorization: Bearer … header is present, it is validated against the token hash table. If the token is invalid, expired, or belongs to a disabled agent, the request is rejected immediately with a 401.
2

Fall back to the session cookie

Only if no Authorization header is present does the gate check the hb_session cookie.
3

Check the anonymous allowlist

If neither credential is present, the request is checked against the open-path allowlist. Allowlisted requests run as the synthetic Guest principal. Everything else receives a 401 (API/MCP) or a redirect to the login page (browser).
An invalid bearer token never falls back to the cookie. This is a fail-closed design: if you provide a Authorization header and it is wrong, you get a 401 regardless of whether a valid session cookie is also present. This prevents a leaked or rotated token from silently downgrading to a different identity.

​
Obtaining a Token

1

Log in to get a session

curl -X POST https://hashboard.example.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"hunter2"}' \
  -c cookies.txt
The hb_session cookie is saved to cookies.txt.
2

Create a bearer token

curl -X POST https://hashboard.example.com/api/v1/tokens \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d '{"name":"my-script"}'
The response body contains a raw field with the full hb_… token string. Save it immediately — it will not be shown again.
3

Use the bearer token

curl https://hashboard.example.com/api/v1/boards \
  -H 'Authorization: Bearer hb_abc123...'
You can now drop the cookie file and use the token directly.

​
Issuing Tokens for Agents

Agents are first-class principals in Hashboard. You can issue a token on behalf of an agent you own by including principalId in the token creation request: 
# Create an agent
curl -X POST https://hashboard.example.com/api/v1/agents \
  -H 'Authorization: Bearer hb_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"displayName":"My Deploy Bot"}'

# Issue a token for the agent (use the id from the response above)
curl -X POST https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"deploy-bot-token","principalId":"AGENT_ID"}'
The agent’s actions — card updates, comments, activity events — are attributed to the agent’s identity, while authorization resolves through the owning human’s visibility grants.

​
Token Expiry and Revocation

Tokens accept an optional expiresAt ISO date string at creation time. To revoke a token before it expires, call DELETE /api/v1/tokens/:id. Disabling an agent (POST /api/v1/agents/:id/disable) immediately stops all of its tokens from authenticating. 
# List your tokens (hashes only — raw values are never returned after creation)
curl https://hashboard.example.com/api/v1/tokens \
  -H 'Authorization: Bearer hb_YOUR_TOKEN'

# Revoke a specific token by id
curl -X DELETE https://hashboard.example.com/api/v1/tokens/TOKEN_ID \
  -H 'Authorization: Bearer hb_YOUR_TOKEN'

​
Unauthenticated Endpoints

The following endpoints do not require any token or cookie:
EndpointDescription
GET /api/v1/healthLiveness check
GET /api/v1/openapi.jsonOpenAPI specification
GET /api/docsScalar interactive UI
GET /llms.txtAgent-oriented overview
POST /api/v1/auth/loginLocal login
POST /api/v1/auth/registerLocal registration (subject to instance settings)

​
Anonymous Access to Shared Resources

Boards, cards, and standalone documents carry a visibility field. Resources set to link-read, link-write, or public are accessible without a token when the request arrives at the resource’s canonical URL. Anonymous requests run as the synthetic Guest principal.
If an unauthenticated request targets a resource the caller is not permitted to see — including a private resource that happens to exist — Hashboard returns 401, never 404. The existence of private resources is never confirmed to anonymous callers.
The complete anonymous surface is strictly allowlisted. It covers the three resource pages and their JSON equivalents, attachment bytes at /attachments/:id, and the specific API verbs that link-write visitors need. Nothing outside that list runs as Guest.

Build docs developers (and LLMs) love

Get started for freeTalk to us