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 inherits the same permissions and access as the user who created it — there are no separate scopes in V1.
Creating a Token
- Open I'mBoard and navigate to Account > API Access
- Click Create Token
- Give it a name (e.g., "my-script") and choose an expiry (30, 90, 180, or 365 days)
- 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 requested action |
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.