> ## 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.

# Identities

> Admin API operations for managing the credential identities a server authenticates with: add, list, delete, enable, disable, set personal-versus-shared availability, and set an identity’s header tokens.

These operations manage identities — the credentials MCP Manager uses to authenticate to a downstream server. A private identity is usable and editable only by its owner; its header token values are write-only and never returned.

<Info>
  **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.
</Info>

## List Identities

<Badge color="green">Read-only</Badge>

List the credential identities attached to an inbound server.

Returns each identity as `{ guid, name, enabled, accessControl, inboundServerGuid }`. `accessControl` is 'private' (only the creator may use it) or 'global' (anyone in the org). The set is scoped to the server's identities the caller is permitted to see.

**MCP tool:** `list_identities` · **REST:** `GET /api/v1/mcpm-admin/servers/:inboundServerGuid/identities` · **Capability:** View all identities (`accessAllIdentities`)

**Parameters**

<ParamField path="inboundServerGuid" type="string" required>
  The guid of the inbound server whose identities to list (from list\_inbound\_servers).
</ParamField>

**Example**

```json theme={null}
{"inboundServerGuid":"MIS-..."}
```

## Add Identity

Add a credential identity to an existing inbound server.

The server's `authenticationType` selects the path:

* **Headers server** — provide `headers`; a new credential identity is created and the headers stored **encrypted**. Returns the identity as `{ guid, name, enabled, accessControl, inboundServerGuid }`.
* **OAuth server** — supply the `oauth*` token fields for headless token injection (returns the server summary, `authenticated` after feature-learn validates the token), or omit them for the interactive flow (returns the server summary with an `authorizationUrl` to relay to the user for approval; the redirect callback then creates the identity). Do not pass `headers` to an OAuth server. On the interactive path the identity exists only after approval — once it does, you can wire it as the shared identity on a gateway assignment or select it when issuing a gateway token.

**MCP tool:** `add_identity` · **REST:** `POST /api/v1/mcpm-admin/servers/:inboundServerGuid/identities` · **Capability:** Identity management (`identityManagement`)

**Parameters**

<ParamField path="inboundServerGuid" type="string" required>
  The guid of the inbound server to add an identity to (from list\_inbound\_servers).
</ParamField>

<ParamField body="headers" type="object">
  Static request headers, as a name → value map. Required when the server uses `headers` auth. Header values are secrets — stored encrypted and never logged. `mcpm-` prefixed headers are reserved and dropped. *(a string → string map)*
</ParamField>

<ParamField body="oauthAccessToken" type="string">
  OAuth access token for headless token injection on an `oauth` server. Secret — never logged.
</ParamField>

<ParamField body="oauthRefreshToken" type="string">
  OAuth refresh token (optional) for headless token injection. Secret — never logged.
</ParamField>

<ParamField body="oauthExpiresAt" type="integer">
  Unix epoch milliseconds at which the access token expires (optional) for headless token injection.
</ParamField>

<ParamField body="oauthTokenEndpoint" type="string">
  The OAuth token endpoint URL, used to refresh the access token. Required for headless token injection.
</ParamField>

<ParamField body="oauthClientId" type="string">
  The OAuth client id. Required for headless token injection.
</ParamField>

<ParamField body="oauthClientSecret" type="string">
  The OAuth client secret (optional — confidential clients only). Secret — never logged.
</ParamField>

<ParamField body="oauthScope" type="string">
  Space-separated OAuth scopes granted to the token (optional) for headless token injection.
</ParamField>

<ParamField body="identityLabel" type="string">
  A name for the new credential identity. Defaults to "\<server> Identity".
</ParamField>

<ParamField body="accessControl" type="string" default="private">
  Who may use the credential: 'private' (only the creator) or 'global' (anyone in the org). Defaults to 'private'. One of: `private`, `global`.
</ParamField>

**Example**

```json theme={null}
{"inboundServerGuid":"MIS-...","headers":{"Authorization":"Bearer <token>"}}
```

## Enable Identity

Enable a credential identity.

Enables the identity. Saved only when the state changes. Returns the identity summary. A private identity you did not create is not visible.

**MCP tool:** `enable_identity` · **REST:** `POST /api/v1/mcpm-admin/identities/:identityGuid/enable` · **Capability:** Identity management (`identityManagement`)

**Parameters**

<ParamField path="identityGuid" type="string" required>
  The guid of the identity to enable (from list\_identities).
</ParamField>

**Example**

```json theme={null}
{"identityGuid":"MISI-..."}
```

## Disable Identity

Disable a credential identity.

Disables the identity so it can no longer authenticate. Saved only when the state changes. Returns the identity summary.

**MCP tool:** `disable_identity` · **REST:** `POST /api/v1/mcpm-admin/identities/:identityGuid/disable` · **Capability:** Identity management (`identityManagement`)

**Parameters**

<ParamField path="identityGuid" type="string" required>
  The guid of the identity to disable (from list\_identities).
</ParamField>

**Example**

```json theme={null}
{"identityGuid":"MISI-..."}
```

## Delete Identity

<Badge color="red">Destructive</Badge>

Delete a credential identity.

Permanently deletes the identity. Its encrypted header credential is not separately deleted (it lingers, org-scoped, and is never exposed). Returns `{ deleted: true, identityGuid }`.

**MCP tool:** `delete_identity` · **REST:** `DELETE /api/v1/mcpm-admin/identities/:identityGuid` · **Capability:** Identity management (`identityManagement`)

**Parameters**

<ParamField path="identityGuid" type="string" required>
  The guid of the identity to delete (from list\_identities).
</ParamField>

**Example**

```json theme={null}
{"identityGuid":"MISI-..."}
```

## Set Identity Availability

Set a credential identity's availability (private or global).

Changes whether the identity is private (creator-only) or global (usable/selectable by anyone in the workspace). CREATOR-ONLY: only the identity's creator may change this, even with the view-all-identities capability. Returns the identity summary.

**MCP tool:** `set_identity_availability` · **REST:** `PATCH /api/v1/mcpm-admin/identities/:identityGuid/availability` · **Capability:** Identity management (`identityManagement`)

**Parameters**

<ParamField path="identityGuid" type="string" required>
  The guid of the identity (from list\_identities).
</ParamField>

<ParamField body="availability" type="string" required>
  'private' (only the creator may use it) or 'global' (anyone in the workspace may use/select it). One of: `private`, `global`.
</ParamField>

**Example**

```json theme={null}
{"identityGuid":"MISI-...","availability":"global"}
```

## Set Identity Headers

Replace a credential identity's header secrets.

Sets (replaces) the encrypted header credentials for a header-authenticated identity. CREATOR-ONLY: only the identity's creator may edit its secrets. Values are write-only — they are never returned by any tool. Returns the identity summary (header names/values are not included).

**MCP tool:** `set_identity_headers` · **REST:** `PUT /api/v1/mcpm-admin/identities/:identityGuid/headers` · **Capability:** Identity management (`identityManagement`)

**Parameters**

<ParamField path="identityGuid" type="string" required>
  The guid of the identity whose header credentials to replace (from list\_identities).
</ParamField>

<ParamField body="headers" type="object" required>
  The full set of request headers (e.g. an Authorization bearer) this identity sends upstream. REPLACES the existing set. Reserved 'mcpm-' and empty entries are dropped. Stored encrypted and never returned. *(a string → string map)*
</ParamField>

**Example**

```json theme={null}
{"identityGuid":"MISI-...","headers":{"Authorization":"Bearer <new-token>"}}
```

## Further reading

<CardGroup cols={2}>
  <Card title="Gateways" icon="arrow-right" href="/admin-api/reference/gateways">
    Where to go next in this section.
  </Card>

  <Card title="Authentication & access" icon="shield-halved" href="/admin-api/authentication">
    Tokens, the entitlement, capability gating, and error codes for every operation here.
  </Card>

  <Card title="Tool & endpoint reference" icon="book" href="/admin-api/reference/overview">
    The full reference index across every domain.
  </Card>

  <Card title="Capabilities" icon="key" href="/deployment/rbac-and-roles/capabilities">
    What each capability named on this page actually allows.
  </Card>
</CardGroup>