Authentication

All API requests require a valid token in the Authorization header.

Personal Access Tokens (PATs)

PATs are the recommended authentication method for scripts, integrations, and AI agents. A token is always bounded by the permissions of the user who created it, and is further restricted to an explicit set of scopes chosen when the token is created.

Scopes follow a resource:action format (for example boards:read, meetings:write). Read and write are independent — boards:write does not imply boards:read. For convenience, the UI offers two presets:

• Read only — view boards, meetings, documents, reports, and other resources; cannot make changes.
• Full access — read and write access to every resource the API supports.

A request whose token is missing the required scope fails with 403 FORBIDDEN. The exact scope required by each MCP tool / REST route is listed in the Claude Code & MCP guide — Tool reference.

Creating a Token

1. Open I'mBoard and navigate to Account > API Access
2. Click Create Token
3. Give it a name (e.g., "my-script")
4. Choose Permissions — either the Read only or Full access preset
5. Choose an expiry (30, 90, 180, 365 days, or no expiry)
6. Copy the token immediately — it is shown only once and cannot be retrieved later

Tokens are prefixed with imb_pat_ so you can identify them in your configuration.

Sending Authenticated Requests

Include the token in the Authorization header on every request:

Authorization: Bearer imb_pat_...

Example with curl:

curl https://app.imboard.ai/api/v1/me \
  -H "Authorization: Bearer $IMBOARD_API_TOKEN"

Token Lifecycle

Revoked and expired tokens fail immediately with a 401 response — there is no grace period.

Revoking a Token

Navigate to Account > API Access, find the token, and click Revoke. The token is invalidated instantly. Any in-flight or future requests using it will fail.

Board Access Tokens (BAT)

A board access token is a board-scoped service principal — use it when an agent or integration should reach exactly one board, read-only, and nothing else. Unlike a PAT, a BAT has no user identity: it does not act as any person, cannot see your profile, your other boards, or portfolio-level data.

Tokens are prefixed with imb_bat_ so you can tell them apart from personal tokens.

When to use a BAT vs a PAT

Choose a BAT for a single-board, read-only agent (a reporting bot, a shared board assistant, a CI job). Choose a PAT for a personal agent that roams across all your boards or needs your profile / portfolio data.

Board scoping and read-only default

A BAT is enforced at the auth layer, not just by convention:

• It is pinned to one board. A request to any other board returns 404 RESOURCE_NOT_FOUND — the API deliberately does not reveal whether the other board exists.
• It is read-only by default. The default preset grants only *:read scopes for that board (boards:read, meetings:read, documents:read, reports:read, notifications:read, audit:read, functions:read). A read-only BAT calling a write route fails with 403 FORBIDDEN. A read-write preset adds the matching *:write scopes but never board create/delete.
• It can only be used on board-scoped routes (/boards/:boardId/...). Account-level or portfolio routes reject a BAT with 403 FORBIDDEN.

Minting a board access token

Board access tokens are managed from the board itself, not your account:

1. Open the board and navigate to Board settings → Access tokens.
2. Click Create board access token. (Every board member can view the token list, but only board owners and admins can create or revoke tokens — non-admins see the list read-only.)
3. Give it a name (e.g., acme-reporting-bot), 1–80 characters, so you can revoke it per-integration later.
4. Choose a scope preset:
   • Read only (default) — read this board's meetings, documents, reports, notifications, audit, and functions.
   • Read & write — read and write this board (never create or delete boards). This is an explicit admin opt-in.
5. Choose an expiry (30, 90, 180, 365 days, or no expiry).
6. Copy the token immediately — it starts with imb_bat_ and is shown only once.

To revoke, return to Board settings → Access tokens and click Revoke on the token. It is invalidated instantly, breaking any agent or tool still using it.

Token management is human-only. A board access token can never mint, list, or revoke board access tokens — those routes require a logged-in owner/admin session, not a token. This prevents a BAT from escalating or laterally minting more tokens. See the Connect an agent / MCP guide for wiring one into an MCP client and verifying the scoping end-to-end.

Sending Authenticated Requests

A BAT is sent the same way as a PAT — in the Authorization header:

Authorization: Bearer imb_bat_...

The token type is transparent to clients: the CLI, the MCP server, and any REST integration accept either prefix with no configuration difference.

JWT Tokens

Browser session JWTs are accepted by the API but are not recommended for programmatic access. They expire with the session and cannot be manually managed. Prefer personal access tokens for all automation and integration use cases.

Identifying a token (whoami)

Not sure what a token is, or which board a board token is pinned to? Call GET /api/v1/whoami. Any authenticated principal — a PAT, a BAT, or a browser JWT — can introspect itself. No scope is required, and the response never includes the token secret.

curl https://app.imboard.ai/api/v1/whoami \
  -H "Authorization: Bearer $IMBOARD_API_TOKEN"

The shape depends on the token type:

Board access token (BAT) — tells you which single board it is scoped to:

{
  "object": "whoami",
  "authType": "board_token",
  "boardId": "665f...",
  "boardName": "Acme Inc.",
  "scopes": [
    "boards:read",
    "meetings:read",
    "documents:read",
    "reports:read",
    "notifications:read",
    "audit:read",
    "functions:read"
  ],
  "tokenName": "acme-reporting-bot",
  "expiresAt": "2026-09-12T00:00:00.000Z"
}

Personal access token (PAT) — tells you which user it acts as:

{
  "object": "whoami",
  "authType": "api_token",
  "userId": "601a...",
  "email": "[email protected]",
  "scopes": ["boards:read", "meetings:read"],
  "tokenName": "my-script",
  "expiresAt": null
}

A browser JWT returns { "object": "whoami", "authType": "jwt", "userId": "...", "email": "..." }.

Use it as a quick sanity check when wiring up an agent: a board_token response confirms the token is board-scoped, and boardId / boardName confirm it is pinned to the board you expect.

Permission and Billing Rules

API requests go through the same permission checks and billing enforcement as the I'mBoard web app:

• If a board's billing state restricts access, the API returns 403 BILLING_RESTRICTED
• If your user role lacks permission for an action, the API returns 403 FORBIDDEN
• If your account is suspended or inactive, all API calls fail with 403

Error Responses

Security Best Practices

• Store tokens securely. Treat them like passwords — use environment variables or a secrets manager, never commit them to source control.
• Use short-lived tokens. Choose the shortest expiry that fits your use case.
• Revoke tokens you no longer need. Regularly audit your active tokens in Account > API Access.
• One token per integration. If a token is compromised, you can revoke it without affecting other integrations.