> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpmanager.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication & access
> The MCP Manager Admin API access model: Personal Access Tokens (mcpm_pat_, SHA-256 hashed at rest, 1–90 day TTL) and OAuth 2.1 with RFC 8707 audience binding, the ff-mcpm-admin entitlement, per-operation capability gating, and the HTTP status codes the API returns on denied, malformed, and failed requests.
Every Admin API request carries a bearer credential and passes three checks in order: the workspace **entitlement**, then the credential's **authenticity**, then the operation's **capability**. This page is the reference for each credential type, the entitlement, capability gating, and the status codes the API returns.
**Closed beta.** The MCP Manager Admin API and MCP server are available now to a
limited set of workspaces through the **MCP Manager Admin API** entitlement
(`ff-mcpm-admin`), ahead of general availability. If you don't see **Settings →
MCP & API** in your workspace, it isn't enabled for you yet — ask your MCP Manager
contact to join the beta.
## Credential types
The Admin API accepts a bearer token in the `Authorization` header on both the MCP and REST surfaces. The token is either a **Personal Access Token** or an **OAuth 2.1** access token; the server tells them apart by prefix — a credential beginning with `mcpm_pat_` is verified as a Personal Access Token, and anything else is verified as an OAuth JWT.
```http theme={null}
Authorization: Bearer mcpm_pat_
```
### Personal Access Tokens
A Personal Access Token (PAT) is a long-lived credential you mint for a headless agent or pipeline. Create, list, and revoke them at [MCP & API → Tokens](https://app.mcpmanager.ai/settings/tokens/tokens) or with the `create_access_token` / `list_access_tokens` / `revoke_access_token` operations.
| Property | Value |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| Format | `mcpm_pat_` followed by 64 hexadecimal characters (32 random bytes) |
| Storage at rest | Only the token's **SHA-256 hash** is persisted; the secret is shown once at creation and cannot be recovered |
| Default lifetime | **90 days** |
| Configurable lifetime | **1–90 days**, or **0** to never expire |
| Displayed identifier | A non-secret prefix (`mcpm_pat_` plus the first 4 characters) and your label |
| Scope | Acts as **you** — carries your user, role, and capabilities |
The plaintext secret is returned **once**, at creation. Because only its SHA-256 hash is stored, MCP Manager cannot show it again — losing it means minting a new token. Each token's **last-used** time is tracked (best-effort, updated at most once every 5 minutes) so you can spot dormant tokens.
**Creating a token is idempotent by label.** If you already hold a valid token with the same label, `create_access_token` returns that token's metadata with `alreadyExisted: true` and `token: null` — the existing secret is never re-shown — rather than minting a duplicate. Choose a new label when you genuinely need a fresh secret. This lets a provisioning pipeline re-run safely without accumulating duplicate tokens.
**Revocation is immediate and scoped to you.** Revoking a token stops it working on the next call and removes it from your list. You can only revoke your **own** tokens; a request to revoke a token you don't own returns `404`.
### OAuth 2.1 access tokens
Interactive MCP clients can authenticate with **OAuth 2.1** instead of a Personal Access Token. The admin MCP server is an OAuth protected resource: a client that lacks a credential receives a `401` whose `WWW-Authenticate` header advertises the protected-resource metadata document per **[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)** (OAuth 2.0 Protected Resource Metadata), and the client then runs the authorization flow to obtain a bearer.
Access tokens are **audience-bound** to the admin MCP resource following **[RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707)** (Resource Indicators for OAuth 2.0): the token's `aud` claim must include the resource `${ROOT_URL}/mcpm-admin/mcp`. A token minted for a different resource is rejected, so an OAuth token issued for one endpoint cannot be replayed against the Admin API. The token's `sub` claim carries the resolved MCP Manager identity, which supplies the user, role, and capabilities for the request.
## The MCP Manager Admin API entitlement
Access to the entire Admin API — every tool and endpoint, and the **Settings → MCP & API** area in the app — is gated by the **MCP Manager Admin API** entitlement (`ff-mcpm-admin`) on your workspace. This is a plan-level feature, not a role capability, so it is checked before anything else on every request.
* A workspace **without** the entitlement receives `403 Forbidden` — *"This organization is not entitled to the MCP & API configuration layer."*
* If the entitlement check itself can't be completed (an upstream lookup fails), the API returns `503 Service Unavailable` — *"Entitlement check failed"* — rather than silently allowing or denying the call. The check fails loud.
If you can reach the app but the **MCP & API** settings area is missing, your workspace isn't in the beta. Access depends on the entitlement, not on any role — ask your MCP Manager contact to enable it.
## Capability gating
Once a request is entitled and authenticated, each operation enforces the **same capability** as the equivalent action in the app. The Admin API never widens what your role permits: if you couldn't do something by hand in the UI, the corresponding tool or endpoint refuses it.
* Most operations require a specific capability — for example, creating a server requires **Basic server management**, querying logs requires **View and export logs**, and editing a role requires **Manage roles**.
* A few operations require **no** capability and are available to any authenticated caller: `whoami`, `list_capabilities`, and managing your **own** access tokens (`create_access_token`, `list_access_tokens`, `revoke_access_token`).
* A call you lack the capability for returns `403 Forbidden` — *"Capability '\' is required."*
Call `list_capabilities` to retrieve every capability key, grouped as it appears in the product, with a label and description — useful before building a role's grants with `create_role` or `modify_role`. Each entry in the [tool & endpoint reference](/admin-api/reference/overview) names the capability it requires. For what each capability allows, see the [capabilities reference](/deployment/rbac-and-roles/capabilities).
## Response status codes
The REST surface returns standard HTTP status codes; the MCP surface surfaces the same failures as tool errors. Every response carries a correlation id you can quote when asking support to trace a request.
| Status | Meaning | Typical cause |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------- |
| `200` | Success | Read or update completed (some creates return `201`) |
| `201` | Created | A new resource was created (for example, an access token) |
| `400` | Bad Request | Input failed schema validation — the message names the offending field |
| `401` | Unauthorized | Missing or invalid bearer credential, or an OAuth token whose audience doesn't match the admin resource |
| `403` | Forbidden | The workspace lacks the entitlement, or your role lacks the required capability |
| `404` | Not Found | The target resource doesn't exist, or isn't yours (for example, another user's token) |
| `500` | Internal Server Error | An unexpected failure; the detail is logged under the correlation id, not returned |
| `503` | Service Unavailable | The entitlement check couldn't be completed |
## What is and isn't exposed
The Admin API is deliberate about secrets. These properties hold across every operation:
* **Token secrets are write-only.** A Personal Access Token's secret is shown once and stored only as a SHA-256 hash.
* **Credential and integration header values are write-only.** Identity header tokens and OpenTelemetry collector headers are stored encrypted; read operations return header **names only**, never their values.
* **Alert debug context is scrubbed at write time.** Sensitive keys — `authorization`, `cookie`, `set-cookie`, `access_token`, `refresh_token`, `client_secret`, `password`, and similar — are replaced with `[REDACTED]` before an alert is stored, so `get_alert` never surfaces a live secret.
## Further reading
Every operation with the capability it enforces and its MCP tool name and REST route.
Create a token and register the admin MCP server in your client.
What each capability allows, grouped exactly as the Admin API groups them.
How MCP Manager stores and brokers the credentials behind every identity.
## External sources
The audience-binding standard the admin server enforces on OAuth access tokens.
The metadata document the `401` challenge advertises so clients can discover the authorization server.