# Identity

> The Identity operations of the Hub REST API (3 operations).

URL: https://docs.synap.live/docs/reference/hub-api/identity · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## GET /discord/identity

Resolve an existing Discord→Synap identity link (read-only)

Returns whether the given Discord user is linked to a Synap user under the calling operator key. NEVER auto-creates a link.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `discordUserId` | query | string | yes |  |

Responses:

- `200`: Link status
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## GET /discord/identity/members

List linkable members of the acting workspace

Returns the human members of the acting (operator) workspace that a Discord user can be linked to via the onboarding picker.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `workspaceId` | query | string |  |  |

Responses:

- `200`: Linkable members
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## POST /discord/identity/link

Link a Discord user to a Synap identity (admin-gated)

Creates the Discord→Synap mapping. mode='existing' maps onto an existing workspace member (impersonation — admin-only). mode='new' provisions a fresh Synap user + team membership (account creation — admin-only). Authorized by the acting context's workspace role (owner/admin), never a caller-supplied flag.

Request body (`application/json`): DiscordIdentityLinkRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `discordUserId` | string | yes |  |
| `mode` | "existing" \| "new" | yes |  |
| `targetUserId` | string |  |  |
| `displayName` | string |  |  |
| `workspaceId` | string |  |  |

Responses:

- `200`: Linked
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error