# Boardeon auth.md

> How an AI agent gets access to a company in Boardeon: OAuth 2.1 sign-in in a browser, registration with the user's e-mail confirmed by the user (service_auth), or a personal access token. Write tools only propose changes; an owner or admin approves each one in Boardeon.

## Who this is for

Agents and MCP clients — Claude, ChatGPT, Hermes Agent, Cursor, VS Code, the OpenAI Responses API, n8n and custom agents — that act for a Boardeon user. One connection can include several of the user's companies (organizations); the agent works with each company separately and with the user's current role in it.

## What the credentials open

- MCP server: `https://boardeon.com/mcp` (Streamable HTTP; protocol 2026-07-28 and the 2025 versions).
- `list_companies` returns the companies of this connection with the user's role in each. When there is more than one, pass `company_id` from that list to every other tool; with a single company it is optional.
- Read tools return company data. Write tools create a proposed action (`status: "proposed"`, `action_id`) that waits for approval; `get_action_status` returns the outcome.
- Scopes:
  - `company:read` — company profile, Business Score, brief, 90-day plan tasks, decisions, opportunities, finance calculations, status of proposed actions
  - `knowledge:read` — search the company knowledge base (documents, notes, decisions, strategy)
  - `knowledge:write` — propose notes for the knowledge base
  - `tasks:write` — propose new tasks and task status changes
  - `decisions:write` — propose decisions to record in the Decision Room
  - `boardroom:run` — reserved for AI Boardroom meetings (no tool uses it yet)
  - `support:write` — propose replies and status changes in the company’s Boardeon support requests

## Discovery

- Protected resource metadata (RFC 9728): https://boardeon.com/.well-known/oauth-protected-resource/mcp (the whole site: https://boardeon.com/.well-known/oauth-protected-resource)
- Authorization server metadata (RFC 8414): https://boardeon.com/.well-known/oauth-authorization-server — includes the `agent_auth` block
- Signing keys (ES256): https://boardeon.com/.well-known/jwks.json
- MCP server card: https://boardeon.com/.well-known/mcp/server-card.json
- A request to the MCP server without a token returns `401` with `WWW-Authenticate: Bearer resource_metadata="https://boardeon.com/.well-known/oauth-protected-resource/mcp"`.

## Method 1 — OAuth 2.1 with PKCE (clients with a browser)

1. Client identity: a Client ID Metadata Document (your `client_id` is the https URL of your metadata document), or Dynamic Client Registration at `POST https://boardeon.com/oauth/register` (public clients only, no client secret).
2. Send the user to `https://boardeon.com/oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `code_challenge` and `code_challenge_method=S256`, `state`, `scope` and `resource=https://boardeon.com/mcp`.
3. The user signs in to Boardeon, ticks one or more companies and the scopes. The redirect carries `code`, `state` and `iss` (RFC 9207).
4. `POST https://boardeon.com/oauth/token` (form-encoded) with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier` and `resource`.
5. You get an access token (JWT, ES256, 60 minutes) and a refresh token. Refresh with `grant_type=refresh_token`; every refresh returns a new refresh token. Retrying the same refresh within 30 seconds, before the new token is used, returns `invalid_grant` and keeps the sign-in; any later reuse of an old refresh token ends the sign-in.
6. The first sign-in grants read access (the 401 challenge lists only read scopes). A write tool called without its scope returns `403` with `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"` — authorize again with that scope (step-up); the user ticks write permissions explicitly.

Redirect URIs: https (any host except this site), `http://localhost`, `http://127.0.0.1` or `http://[::1]` with any port, `cursor://` and `vscode://`.

## Method 2 — agent registration with the user's e-mail (service_auth)

For agents without a browser.

1. `POST https://boardeon.com/oauth/agent/identity` with JSON `{"type": "service_auth", "login_hint": "<user e-mail>", "agent_name": "<your agent>", "scope": "company:read knowledge:read"}`. Without `scope` the request covers read access only; write scopes must be named, and the user ticks them explicitly. The older shape `{"type": "identity_assertion", "assertion_type": "verified_email", "assertion": "<user e-mail>"}` is accepted the same way: the user still confirms the address.
2. The response has `claim_token` (keep it secret), `claim.user_code`, `claim.verification_uri`, `claim.interval` and `claim.expires_in`. It is the same whether or not the address has a Boardeon account.
3. Give the user the `verification_uri` and the `user_code`. The user signs in to Boardeon with that e-mail address, sees your agent's name, identifier, the time and the country the request came from, ticks one or more companies and the scopes, and types the code. Five wrong codes close the registration. The user and the company's owners get an e-mail about every new connection.
4. Poll `POST https://boardeon.com/oauth/token` with `grant_type=urn:workos:agent-auth:grant-type:claim` and `claim_token` every `interval` seconds (5 s): `authorization_pending` — keep polling; `slow_down` — add 5 seconds; `expired_token` — get a new code with `POST https://boardeon.com/oauth/agent/claim` and `{"claim_token": "…", "login_hint": "<same e-mail>"}`.
5. Success returns `access_token`, `refresh_token` and your `client_id`. Refresh as in method 1. The registration is valid for 24 hours; tokens are issued once.

## Method 3 — personal access token

For clients without OAuth (OpenAI Responses API, n8n, scripts). The user creates a token in Boardeon under Settings → AI agents (https://boardeon.com/settings/agents), ticks one or more companies, the scopes and the expiry, and gives it to the agent. It starts with `bdn_pat_` and is shown once.

## Using the credentials

- Send `Authorization: Bearer <token>` to `https://boardeon.com/mcp`. Never put a token in a URL.
- `401` with `error="invalid_token"`: refresh the access token, or sign in again.
- An error result from a tool (`isError: true`) explains what is missing: a scope, the user's role or the company's plan, or a `company_id` (`company_required`, `unknown_company` — call `list_companies`).

## Revocation

- `POST https://boardeon.com/oauth/revoke` with `token=<token>` (RFC 7009): a refresh or access token ends that sign-in; a personal access token is revoked.
- The user can disconnect any app or token in Settings → AI agents; it stops working on the next request.
- Changing the password disconnects all of the user's apps and personal access tokens; leaving or being removed from a company disconnects them in that company only — other companies of the same connection keep working. In Settings → AI agents the user can disconnect a single company or the whole app.

## Limits

- MCP: 120 requests a minute per connection, 3000 an hour per company; 60 proposed actions an hour per company.
- Token endpoint: 120 code exchanges a minute per client, 10 refreshes a minute per refresh token, 30 polls a minute per claim token; client registration: 100 an hour and agent registration: 10 an hour per IP address.
- 30 invalid tokens a minute from one IP address block further token checks for that minute.
- The number of connected apps depends on each company's plan; a company that has reached its limit is skipped and the others connect.

## Policies

Terms of Service: https://boardeon.com/legal/terms · Privacy Policy: https://boardeon.com/legal/privacy · Contact: support@boardeon.com
