> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onboardme.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and permissions

> Sign in with OnboardMe (OAuth) or a practice API key. How scopes, roles and write access decide what the assistant can do.

Every request to `/mcp` must be authenticated. There are two ways in.

| | Sign in with OnboardMe (OAuth) | API key |
| - | - | - |
| Best for | Claude, ChatGPT, Cursor, Claude Code | Server-to-server tools, clients that send headers |
| Acts as | The staff member who signed in | The practice API client |
| Access | Read-only or Read & write, chosen at sign-in | `canWrite` on the API client |
| Webhook tools | Not available | Available |

## Sign in with OnboardMe (OAuth)

The server follows the MCP authorization spec (OAuth 2.1 with PKCE). Clients that support MCP OAuth handle these steps automatically:

1. The client calls `/mcp` without a token and gets `401` with a `WWW-Authenticate` header that points to `/.well-known/oauth-protected-resource/mcp`.
2. That metadata names the [regional API](/mcp/regions) as the authorization server. The client reads its metadata at `/.well-known/oauth-authorization-server`.
3. The client registers itself (`/oauth/register`) and sends you to the OnboardMe consent page.
4. You sign in, choose the practice, and choose **Read-only** or **Read & write**.
5. The client exchanges the code at `/oauth/token` and calls `/mcp` with `Authorization: Bearer <token>`. Refresh tokens keep the connection alive.

### Scopes

| Scope | Grants |
| - | - |
| `onboardme.read` | Read-only tools |
| `onboardme.write` | Read and write tools (always comes with `onboardme.read`) |

Users with the **Read Only** role always get read access, even if they choose Read & write.

### What the assistant can do

* A read grant only sees read-only tools. A tool that is hidden cannot be called by name.
* A write grant sees every tool except the webhook tools. Webhooks belong to API clients, not to individual users.
* Every action still checks the signed-in user's OnboardMe role. If the role doesn't allow an action, the tool returns `403`.

### Revoke access

Staff can see and revoke their own connections under **Profile → Connected apps** in OnboardMe. Administrators can review and revoke connections for the whole practice from **Settings → Integrations**. Revocation takes effect within about 30 seconds.

### Supported clients

Sign-in redirects are allowed for Claude (claude.ai and claude.com), ChatGPT, Cursor and local tools that use `http://localhost` or `http://127.0.0.1` callbacks. If your client uses another redirect URL, contact [support@onboardme.app](mailto:support@onboardme.app).

## API key

Send the practice API client's credentials on every MCP request, exactly as you would for the [Partner API](/authentication):

```http theme={null}
X-OM-Auth-ID: YOUR_CLIENT_ID
X-OM-Auth-Key: YOUR_CLIENT_SECRET
```

Or use HTTP Basic with the Client ID as username and the secret as password. The MCP server forwards the credentials to the API, which checks them on each call. Write tools need `canWrite` on the API client.

## Rate limits

| Limit | Default |
| - | - |
| Requests without valid credentials, per IP address | 60 per minute |
| Requests per signed-in token or API client | 300 per minute |

Rejected requests return `429` with a `Retry-After` header. The [Partner API's own limits](/errors) also apply to the calls each tool makes.

## Security notes

* Tokens and secrets are never logged and are only sent to the regional API.
* Tools that create users, bills, AML checks, identity verifications, renewals or webhooks are marked destructive, so clients can ask you before running them.
* Tax file numbers and other tax IDs, Director IDs and other ID numbers, dates of birth and bank account details are masked in every tool response (for example `*****123`). They cannot be revealed through the MCP server.
* The server tells the assistant to treat client-entered content (notes, eForm answers) as data, never as instructions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.