Authentication & RBAC

The hosted Metadot MCP endpoint at https://metadot.eu/api/mcp authenticates every request via OAuth 2.1 with PKCE. When you add the URL to your AI tool, your browser opens a consent page — you sign in with your existing Metadot account and your client receives a short-lived bearer token. Refreshes happen silently in the background.

Every tool call then passes through three layers of authorization before any data is read or modified.

OAuth Flow

On first connection your MCP client performs these steps automatically:

1. Discovery — client fetches https://metadot.eu/.well-known/oauth-authorization-server for endpoint metadata
2. Dynamic client registration (RFC 7591) — client registers itself with Metadot's OAuth server
3. Authorization — your browser opens to a Metadot consent page; you sign in and approve
4. Token exchange — client exchanges the authorization code for a 24-hour access token + refresh token
5. Subsequent calls — every MCP request sends Authorization: Bearer <access_token>; the access token refreshes silently via the refresh token

No API keys, no database credentials, no manual token paste. Access tokens expire after 24 hours and refresh automatically.

RBAC (Three Layers)

Every tool call passes through three authorization layers:

Layer	Check	Example
1. Workspace Scope	Which of your workspaces does this call target?	You must be a member of the workspace
2. Workspace Role	Is the user a member? Owners/admins bypass layer 3.	Admin gets full access to all apps
3. App-Level Role	Does the user have a role for this specific app?	crm:manage_contacts permission required for writes

Read vs Write Permissions

• Read tools (search, list, get) require any app role
• Write tools (create, update, delete) require a specific permission such as crm:manage_contacts or tickets:manage_tickets

What Happens When Access Is Denied

If any layer denies access, the tool returns a clear error message explaining which permission is missing. The AI agent will relay this to you so you can ask your workspace admin for the appropriate role.

Workspace Resolution

All module tools require a workspace_id parameter. Call the list_workspaces tool first to discover available workspace IDs, names, slugs, and your role in each.

The server caches workspace resolution results in memory with a 5-minute TTL to avoid repeated database queries while still reflecting role changes within a reasonable window.

Personal Access Token (PAT) Authentication

For agents, scripts, CI pipelines, and tools that cannot open a browser for OAuth, authenticate with a Personal Access Token instead.

How It Works

1. Generate a PAT from Settings → API Keys → Personal Access Tokens in any workspace
2. Pass it as a Bearer token: Authorization: Bearer mk_your_token_here
3. The MCP endpoint validates the token and builds the same auth context as OAuth — same RBAC, same tool access

No browser, no redirect, no client registration. Just a single header.

OAuth vs PAT

	OAuth 2.1	Personal Access Token
Auth flow	Browser-based consent	No browser needed
Token lifetime	24 hours (auto-refresh)	Never expires (until revoked)
Scopes	Full access (*)	Per-module (e.g. crm:*, tickets:*)
Best for	Humans using AI tools	Agents, scripts, CI pipelines
Workspace scope	All user's workspaces	All workspaces (PAT) or one workspace (workspace key)

Scope Enforcement

PATs have per-module scopes. If your PAT has scopes: ["crm:*", "tickets:*"], only CRM and Tickets tools will be available via MCP. Tools for other modules will return a clear scope error. Generate a PAT with * scope for full access.

Generating a PAT

Go to Settings → API Keys → Personal Access Tokens → Generate personal token. Choose your scopes and copy the token — it is shown only once.