> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/balkanid-mcp/authentication-and-permissions.md).

# Authentication and Permissions

### Overview

BalkanID MCP authorizes every tool call using:

1. **How you connect** — OAuth (preferred) or API key
2. **Scopes** — Read and/or Write on the client connection or key
3. **Your BalkanID role** — Reviewer, Risk Manager, or Administrator

The BalkanID platform remains the source of truth for authorization. MCP additionally hides tools you cannot use so your AI assistant only sees relevant options.

### Connection methods

#### OAuth (recommended)

OAuth is the preferred way to connect. Supported clients (for example Claude connectors, Cursor, VS Code, and Claude Code) can sign you in with BalkanID, let you pick a tenant, and complete consent — without pasting a long-lived secret into a config file.

{% hint style="info" %}
**OAuth scopes today:** OAuth consent currently requires **both Read and Write**. Read-only OAuth is not available yet. Partial (per-scope) OAuth consent is planned; until then, OAuth sessions receive both scopes. Use an **API key** if you need a Read-only connection.
{% endhint %}

For client setup, start with [Installation and Setup](/balkanid-mcp/installation-and-setup.md).

#### API key

Use an API key when OAuth is unavailable, or when you need **Read-only** or other scoped access that OAuth does not yet support.

Create a key in the [MCP UI](https://mcp.app.balkan.id) or as an **Employee API Key** in the main BalkanID application with MCP scopes (`MCP_READ` / `MCP_WRITE`).

Clients send:

```http
Authorization: Bearer {tenantId}-{keyId}:{secret}
```

{% hint style="info" %}
API keys may remain active for at most **90 days**. Rotate keys regularly and revoke unused keys in the MCP UI or Employee API Keys.
{% endhint %}

### Scopes vs roles

**Scopes** limit what a specific client connection or API key is allowed to attempt (client/key scoping).

**Roles** are BalkanID RBAC — the same Reviewer / Risk Manager / Administrator capabilities you have in the main BalkanID application. MCP role gates are **derived from your main app roles and capabilities**.

Both apply on every tool call. A Write-scoped key still cannot sync an integration unless your BalkanID role allows it; an Administrator with a Read-only key cannot approve reviews until Write is granted.

### Scopes

| Scope     | Allows                                                                                                                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Read**  | Listing and viewing: identities, credentials, employees, campaigns, requests, Purposes, Constraints, integrations, and related discovery tools                                             |
| **Write** | Changing data: create/edit employees, sync integrations, approve/reject/delegate reviews and requests, create Purpose requests, assign/unassign Purposes, create/update/delete Constraints |

Use least privilege for API keys: start with **Read** unless you need the assistant to take mutating actions. OAuth currently always grants both scopes (see note above).

### Roles

Roles are hierarchical: **Reviewer ⊂ Risk Manager ⊂ Administrator**.

| Role              | Typical MCP capabilities (within your scopes)                                                                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reviewer**      | Reviews, requests, Purposes, read-only discovery (identities, connections, resources, credentials, relations, employees, integrations, Constraints), `whoami`, `help` |
| **Risk Manager**  | Everything a Reviewer can do, plus `list_campaigns` and create/update/delete Constraints                                                                              |
| **Administrator** | Everything a Risk Manager can do, plus `sync_integration`, `create_employee`, and `edit_employee`                                                                     |

Examples:

* A Reviewer with **Read + Write** can approve reviews, but cannot sync integrations.
* An Administrator with **Read only** can list campaigns and employees, but cannot sync or create employees until Write is granted.

### Security best practices

* Prefer **OAuth** for day-to-day use so credentials are not stored in local config files
* Prefer **Read** API keys for investigation-only assistants (OAuth cannot be Read-only yet)
* Create separate API keys per client when not using OAuth (for example one for Cursor, one for Claude Desktop)
* Name keys clearly and set the shortest practical expiry
* Revoke keys when a laptop is lost, a contractor leaves, or a key may be exposed
* Do not commit MCP tokens to git or shared docs
* Remember: the assistant can only do what **you** can do with that connection and role


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.balkan.id/balkanid-mcp/authentication-and-permissions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.