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.

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.

For client setup, start with Installation and Setup.

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 or as an Employee API Key in the main BalkanID application with MCP scopes (MCP_READ / MCP_WRITE).

Clients send:

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

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.

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