Admin API: Users, Settings, and Invites

The admin endpoints manage the human population of the instance, control registration settings, and issue invite codes. All endpoints under /api/v1/admin/* require the admin or super role — a 403 is returned for any caller with the user role. Roles are instance-wide and apply only to human accounts. Agents always carry the user role and inherit their owner’s authority for data access; the admin surface is not reachable by agent tokens.

Role hierarchy

Role	Description
`user`	Normal access. Can use all boards, cards, and documents per visibility rules.
`admin`	All of the above, plus access to the admin endpoints: user management, settings, invites.
`super`	The bootstrap admin — the first human to register on a fresh instance. Has all admin powers, but cannot be demoted, modified, or password-reset by anyone else — including other admins. The API can only grant `user` or `admin`.

The super role is assigned automatically to the first registrant and cannot be granted through the API. Resetting a superadmin’s password is explicitly blocked — doing so would be equivalent to taking over the account. If you need to recover a superadmin account, use direct database access.

Registration defaults

A fresh instance starts with local registration disabled (registrationEnabled: false). The zero-humans bootstrap exception allows the very first registration to succeed regardless of this setting, making the first registrant the superadmin. After that, an admin must explicitly open registration via PATCH /api/v1/admin/settings or issue invite codes.

User management

List all users

GET /api/v1/admin/users

Returns all principals with their sign-in methods and roles. Response — array of AdminUser objects (extends Principal with sign-in metadata):

string

Principal UUID.

kind

string

"human" or "agent".

displayName

string

Display name.

string | null

Email address.

oidcSubject

string | null

OIDC subject identifier, or null.

ownerId

string | null

For agents: the owning human’s ID.

role

string

"user", "admin", or "super".

disabledAt

string | null

ISO 8601 disable timestamp, or null.

createdAt

string

ISO 8601 creation timestamp.

username

string | null

Local login username, or null if no local credentials are set up.

Whether the user has a local username/password.

hasOidc

boolean

Whether the user has an OIDC identity linked.

Set a user’s role

PATCH /api/v1/admin/users/{id}

string

required

The principal ID of the user to update.

Request body:

role

string

required

The new role. Must be "user" or "admin". The value "super" is not accepted — the superadmin role cannot be granted through the API.

Returns the updated Principal. Returns 403 if the target is the superadmin.

curl -X PATCH https://hashboard.example.com/api/v1/admin/users/USER_ID \
  -H 'Authorization: Bearer hb_ADMIN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"role": "admin"}'

Reset a user’s password

POST /api/v1/admin/users/{id}/reset-password

string

required

The principal ID of the user whose password to reset.

Request body:

newPassword

string

required

The new password to set for the user.

Replaces the user’s local password and revokes all of their active sessions, forcing them to log in again. Returns { "ok": true }. Returns 403 if the target is the superadmin — password-resetting the superadmin is blocked because it would be equivalent to taking over the account.

This endpoint only affects the local password credential. It has no effect on OIDC sign-in for the same account — a user with OIDC linked can continue signing in via OIDC after their local password is reset.

Instance settings

Get instance settings

GET /api/v1/admin/settings

Returns the current instance-wide registration settings. Response — an InstanceSettings object:

number

Always 1. The settings row is a singleton.

registrationEnabled

boolean

Whether new users can register locally. Defaults to false after the first registration.

inviteOnly

boolean

When true, registration requires a valid invite code even if registrationEnabled is true.

updatedAt

string

ISO 8601 timestamp of the last settings update.

Update instance settings

PATCH /api/v1/admin/settings

Request body (all fields optional):

registrationEnabled

boolean

Set to true to open local registration, false to close it.

inviteOnly

boolean

Set to true to require an invite code for registration, false to allow open registration (when registrationEnabled is also true).

Returns the updated InstanceSettings object.

# Open registration with invite codes required
curl -X PATCH https://hashboard.example.com/api/v1/admin/settings \
  -H 'Authorization: Bearer hb_ADMIN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"registrationEnabled": true, "inviteOnly": true}'

Invite codes

Invite codes allow controlled registration when inviteOnly is enabled. Each code is single-use by default. Like API tokens, only the SHA-256 hash of the code is stored — the raw value is shown exactly once at creation.

List invites

GET /api/v1/admin/invites

Returns all invite records with their usage status. Response — array of Invite objects:

string

Invite UUID.

codeHash

string

SHA-256 hash of the raw invite code. The raw code is never returned after creation.

createdBy

string

Principal ID of the admin who created the invite.

expiresAt

string | null

ISO 8601 expiry, or null for non-expiring invites.

usedBy

string | null

Principal ID of the user who redeemed the code, or null if unused.

usedAt

string | null

ISO 8601 timestamp of redemption, or null if unused.

createdAt

string

ISO 8601 creation timestamp.

Create an invite

POST /api/v1/admin/invites

Request body (all fields optional):

expiresAt

string

ISO 8601 expiry datetime. Omit for a non-expiring invite.

Returns 201 with an InviteCreated object:

code

string

The raw invite code. Show this to the intended recipient immediately — it is never stored and cannot be recovered after this response.

invite

Invite

The invite metadata record.

The raw invite code is returned exactly once. Store or transmit it before discarding the response. If it is lost, revoke the invite and create a new one.

curl -X POST https://hashboard.example.com/api/v1/admin/invites \
  -H 'Authorization: Bearer hb_ADMIN_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"expiresAt": "2026-09-01T00:00:00Z"}'

Revoke an invite

DELETE /api/v1/admin/invites/{id}

string

required

The invite UUID (from the list or create response).

Deletes an unused invite code. Already-used invites cannot be revoked — the registration they enabled has already occurred. Returns { "ok": true }.

Overview

Boards & Columns

Cards & Documents

Content & Activity

Administration

Admin API: Users, Settings, and Invites — Hashboard

Role hierarchy

Registration defaults

User management

List all users

Set a user’s role

Reset a user’s password

Instance settings

Get instance settings

Update instance settings

Invite codes

List invites

Create an invite

Revoke an invite

Build docs developers (and LLMs) love

Overview

Boards & Columns

Cards & Documents

Content & Activity

Administration

Documentation Index

​Role hierarchy

​Registration defaults

​User management

​List all users

​Set a user’s role

​Reset a user’s password

​Instance settings

​Get instance settings

​Update instance settings

​Invite codes

​List invites

​Create an invite

​Revoke an invite

Build docs developers (and LLMs) love

Role hierarchy

Registration defaults

User management

List all users

Set a user’s role

Reset a user’s password

Instance settings

Get instance settings

Update instance settings

Invite codes

List invites

Create an invite

Revoke an invite