Authentication
All API requests require a valid token in the Authorization header.
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
- Open I'mBoard and navigate to Account > API Access
- Click Create Token
- Give it a name (e.g., "my-script")
- Choose Permissions — either the Read only or Full access preset
- Choose an expiry (30, 90, 180, 365 days, or no expiry)
- 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
| State | Meaning |
|---|---|
| Active | Token is valid and can authenticate requests |
| Expired | Token passed its expiry date and is permanently unusable |
| Revoked | Token was manually revoked by the user and is permanently unusable |
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.
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.
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
| Code | Status | When |
|---|---|---|
UNAUTHENTICATED | 401 | No token provided or header format is invalid |
INVALID_API_TOKEN | 401 | Token is expired, revoked, or not found |
ACCOUNT_SUSPENDED | 403 | User account is suspended — contact support |
ACCOUNT_INACTIVE | 403 | User account is inactive — reactivate in settings |
FORBIDDEN | 403 | User role lacks permission for the action, or the token is missing the required scope |
BILLING_RESTRICTED | 403 | Board billing state blocks this operation |
RATE_LIMITED | 429 | Too many requests — see Rate Limiting |
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.