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

# Authentication

> OAuth 2.1 with your own Koalr login. What the consent screen grants, how tokens are scoped, and how to revoke.

The MCP server authenticates every request with an OAuth access token issued for your Koalr account. There are no API keys to copy and nothing to store in a config file beyond the server URL.

## The flow

1. Your client discovers the server's OAuth metadata from the server URL.
2. A browser window opens on Koalr's sign-in. Sign in as you normally would.
3. A **consent screen** names the client and the access being granted. Approve it.
4. The client receives a token and starts calling tools.

## What a token grants

* **Your identity.** Tools run as you, with exactly your permissions: the workspaces you belong to and the sites you are assigned to.
* **Read-only access.** There are no write scopes.

A token does not grant access to any organisation you are not a member of, and adding you to a new workspace in Koalr makes it visible on the next `list_workspaces` call without reconnecting.

## Disconnecting

* Remove the server from your client and the agent stops immediately.
* Sign-ins are short-lived and expire within 24 hours. If you need a connection cut off sooner, email [support@koalr.ai](mailto:support@koalr.ai) and say which client you used.
* Membership is checked live on every call, so if you are removed from a workspace, access stops within seconds rather than when the sign-in expires.

## Multiple workspaces

Agencies do not need one connection per client. You choose a default workspace when you sign in, and your agent can switch to any other workspace you belong to by passing its `org_id`. Ask it to "list my workspaces" to see them.

## Errors

| Status  | Meaning                                                                 |
| ------- | ----------------------------------------------------------------------- |
| **401** | No valid token, or the sign-in has expired. Reconnect and sign in again |
| **403** | Valid token, but the org or site is outside your access                 |
| **429** | Rate limited. See [Limits and security](/api/mcp/limits-and-security)   |
| **503** | Koalr could not verify the token right now. Retry; do not reconnect     |