> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Identities

# Identities

An identity is a person your gateway knows by name, for example `Alice`. The person and their
linked accounts live in one place in the gateway config:

```json5 theme={"dark"}
{
  session: {
    identityLinks: {
      Alice: ["telegram:123456789", "slack:U061CR7GN"],
    },
  },
}
```

The key is the canonical identity used everywhere a person matters: sender attribution, workspace
lanes, cron and heartbeat `identity` fields, and cross-channel DM session merging. The values are
provider-prefixed channel identities: `telegram:<id>`, `discord:<id>`, `oauth:<provider>:<subject>`
and so on. Devices are not listed here: a paired device's person is recorded on its pairing record
(see [Conflicts and devices](#conflicts-and-devices)).

You never edit that map by hand. Every proof of control ends in one core link operation, exposed as
the `identity` CLI commands and the gateway `identity.*` RPCs, that writes the config for you.

## Creating an identity

```bash theme={"dark"}
wednesdayai identity add Alice
```

Prints `Added identity Alice.`, or `Alice already exists.` if the name is taken. Names allow
letters, digits, `.`, `_` and `-`, up to 64 characters. The names `prototype`, `constructor` and
`__proto__` are reserved and refused, as is the `raw~` prefix (it marks contained unlinked-sender
session buckets).

Identities are never created implicitly. Every linking flow below, `wednesdayai qr --identity`,
`pairing approve --identity` and `oidc invite`, resolves an existing name first and fails on a
typo, so a misspelling cannot mint a person.

## Proofs of control

A link value joins a person only after someone proves control of it. There are four proofs:

### 1. Operator QR (web client)

```bash theme={"dark"}
wednesdayai identity link Alice --qr
# or, equivalently:
wednesdayai qr --client openclaw-user-client --identity Alice
```

The command prints the setup code / QR for the web client. When the browser redeems it on first
connect, its device credential is paired and linked to `Alice` in one step; no `devices link`
follow-up is needed. With `--qr` you can also pass `--setup-code-only`, `--no-ascii` and `--json`
to `identity link`.

Once at least one identity exists, `wednesdayai qr --client openclaw-user-client` refuses to issue
a bootstrap without `--identity`:

```
--identity <name> is required with --client openclaw-user-client once identities exist. Run "wednesdayai identity list" to see them.
```

An unknown identity fails before anything is issued:

```
Unknown identity "Alic". Known identities: Alice. Add it with: wednesdayai identity add Alic
```

On an install with no identities at all the copy is:

```
No identities are set up yet. Add one with: wednesdayai identity add <name>
```

### 2. Operator channel-pairing approval

```bash theme={"dark"}
wednesdayai pairing approve telegram <code> --identity Alice
```

The identity is resolved **before** the one-time pairing code is consumed, so a typo never burns
the code. After approval the sender is linked as `telegram:<id>` to `Alice`. If the link write
fails, the approval stands and the command prints the exact follow-up:

```
Approved, but linking failed: <reason>. Link it with: wednesdayai identity link Alice telegram:<id>
```

### 3. Self-service link code

A person links their own chat account without operator involvement:

1. In a **direct message** to the bot, the person sends `/link`.

2. The bot replies with an 8-character code, valid for one hour, single use (at most 3 pending per
   channel):

   ```
   Your link code: ABCD2345
   In the WednesdayAI app open your account menu → Linked accounts and enter it within 1 hour.
   ```

3. A person who is already linked opens the web client, chooses **Account menu → Linked accounts**
   and enters the code.

Redeeming the code links the sender's `<channel>:<id>` to the linked person's identity **and**
approves the pairing code, so a linked person can vouch for their own chat account when the channel
runs `dmPolicy: "pairing"`. The code grants nothing on its own: sending `/link` only queues a
request, and the claimant must already be a linked person on a paired browser. Only codes issued
by `/link` are claimable: the code a stranger receives from the ordinary `dmPolicy: "pairing"` reply
is not, so admitting a new sender stays an operator decision (`wednesdayai pairing approve`).

The web client shows these errors:

* Unknown or expired code: `That code isn't valid or has expired.`
* Too many attempts: `Too many attempts. Try again in a few minutes.` (5 attempts per device and 15
  per person per minute, then a 5-minute lockout)
* Conflict: `That account is already linked to someone else. Ask your administrator.`

### 4. OIDC sign-in

With the bundled `identity-oidc` plugin enabled, a person signs in with Google, Microsoft Entra or
GitHub; a provider-verified invite links the sign-in to the person and enrolls the browser. See
[Identity OIDC](https://docs.wednesdayai.dev/next/developers/plugins/identity-oidc).

## Listing and unlinking

```bash theme={"dark"}
wednesdayai identity list           # table of Identity | Links
wednesdayai identity list --json

wednesdayai identity unlink telegram:123456789
```

`identity unlink <value>` removes the value from every identity and prints
`Unlinked telegram:123456789 from Alice.`, or `telegram:123456789 is not linked.` It refuses
`device:` values: unlinking a device deregisters it, which is `wednesdayai devices unlink`.

## Conflicts and devices

A chat or OAuth value belongs to exactly one person. Linking a value another person already owns is
refused with `identity_link_conflict`:

```
telegram:123456789 is already linked to Bob. Unlink it first: wednesdayai identity unlink telegram:123456789
```

Ownership is resolved canonically: a legacy config entry that holds a bare `"123"` still owns
`telegram:123`. Link-code claims are serialized per claimed value, so two people redeeming codes
for the same sender cannot interleave their ownership check, link and approval.

Devices are linked with their own command. `identity link` refuses `device:` values and points you
at the device command:

```
Use "wednesdayai devices link <deviceId> --identity <name>" for devices.
```

A device belongs to one person for good. Its person is stored on its pairing record (the
`owner_person` column of `pairing_devices` in the session database), not in `session.identityLinks`.
`wednesdayai devices link <deviceId> --identity <name>` sets it once; linking the same person again
is a no-op, and a device another person owns is refused. The only rebind path is deregister then
re-pair: `devices remove` or `devices unlink` (they are the same: the device's pairing record, its
tokens and its person go together, then its connections close), then pair again, which creates a
new device record, even for the same person. A setup code bound to a different person cannot
rebind a paired device either (`bootstrap_device_owned`). Node-only devices have no person and are
never linked.

`device:` values in `session.identityLinks` confer nothing. On startup the gateway moves each
one for a paired device that is not node-only onto that device's record (a device listed under
several people goes to the first, the person it resolved to before), logs and skips the rest, and
strips them all from the config. `config.set`, `config.patch` and
`config.apply` refuse a write that adds one (`DEVICE_LINK_VALUE_REFUSED`). The
[Control UI v2](https://docs.wednesdayai.dev/next/admin/web/control-ui-v2.md) console can link a paired device to a person or unlink
(deregister) it from the **Nodes & devices** page (Fleet group), over the `device.identity.link`
and `device.identity.unlink` RPCs (both need `operator.admin`). See [devices](https://docs.wednesdayai.dev/next/users/cli/devices.md).

## What a linked device can see

Linking a device to a person also limits what that device sees. A connection without
`operator.admin` whose device is linked to a person receives chat and agent events, node pushes
(for example on WednesdayAI Glass), `chat.history`, `chat.send` and `sessions.list` only for:

* conversations that person owns: a direct conversation belongs to the person who started it, or
  to the first linked person who chats in it, and never changes hands after that; and
* conversations nobody owns, such as the shared main session, group chats and cron sessions.

Another person's session answers `session not found`. Connections with `operator.admin` and
operator or web devices linked to nobody keep full visibility, so a single-person install behaves
as before. A linked node (a device connected as a node and linked to a person) sees that person's
conversations and the shared ones. A node install linked to nobody has no person: it gets only
sessions nobody owns. Other session methods (for example `sessions.describe` or `sessions.patch`)
are not limited yet.

Each sign-in is its own device. When two people sign in to the web client from the same browser,
each sign-in pairs a separate device linked to that person, and each connection sees only its own
person's sessions. A connection keeps the person it signed in as: if its device is later linked to
someone else, that open connection stops seeing either person's sessions until it signs in again.
A message from that connection is refused if it reaches the gateway's admission check after the
relink; a message admitted before the relink still runs. A conversation stays with its owner: a
message sent into it from an admin connection or an unlinked device does not change who owns it,
and the reply is delivered only to the owner's devices (and to the sender). Resetting a session
(`/new`) starts a new conversation; the old one keeps its owner. If a message is refused because
its conversation now belongs to someone else, only the sender gets "session changed, retry".

Unlinking or removing a device (`devices unlink`, `devices remove`, or **Log out** in the web
client) also closes that device's open connections, including one that was still connecting. It
reconnects as whatever it is then paired and linked as.

A WednesdayAI app device's companion browser (ADR 2242) always stays with the app's person:
unlinking or removing the app removes its companions, a companion itself cannot be linked to a
different person, and a companion setup code redeemed by a device another person already owns is
refused with `bootstrap_device_owned` (see
[Device companions and device.self](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md#device-companions-and-deviceself)).

## Gateway RPCs

The CLI talks to the same gateway methods every client uses:

| Method | Scope | Notes |
| - | - | - |
| `identity.list` | `operator.read` | list identities and links |
| `identity.self` | `operator.read` (narrow) | reads the calling device's person and links |
| `identity.add` | `operator.admin` | create a person |
| `identity.link` | `operator.admin` | link a value to a person |
| `identity.unlink` | `operator.admin` | remove a value everywhere |
| `identity.link.claim` | `operator.write` (narrow) | redeem a `/link` code |
| `identity.logout` | `operator.write` (narrow) | log the calling browser out |

The narrow methods read the verified device id from the connection, never from the request body, so
a caller can only act on its own device and person. See [Protocol](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md) for the scope
model.

## What logout does

**Log out** in the web client asks the gateway to run `identity.logout` (waiting up to 3 seconds),
then always clears the browser's own credential and keypair. When the call reaches the gateway it:

* deregisters the paired device server side: its pairing record, tokens and person go together,
  then its connections close.
* removes any companion devices it issued (a WednesdayAI app device's browser companions).

If the gateway is unreachable, the browser still forgets itself but the paired device remains;
remove it with `wednesdayai devices remove <deviceId>`. The next sign-in pairs a fresh device. The
keypair is rotated because a paired browser belongs to one person: keeping it would let the next
person inherit the previous person's device.

A `#setup=<token>` link (an enrollment bootstrap) that arrives at a browser which is already paired
is never redeemed automatically. The web client shows a confirmation naming the consequence, and
only after you confirm does it log the current device out and re-pair under the new identity. On a
browser with no stored credential, redemption is automatic. Every redemption pairs a fresh
keypair: an orphaned one (its token was cleared but the keypair remained) is rotated, and when
another gateway's credential on the same origin still uses the browser's keypair, the new pairing
gets a keypair of its own instead, so neither pairing is broken.

The web client's person always comes from the device credential its own sign-in minted, never from
a per-browser link: every sign-in pairs a new device, and logout forgets it. A setup code for
another person therefore cannot rebind a paired browser; the gateway refuses it, which is why the
confirmation logs the browser out first.

## The account-linking switch

`gateway.webClient.accountLinking` (default `true`) gates the self-service path. Set it to `false`
to keep all linking operator-only: `/link` replies
`Account linking is turned off on this gateway.` and `identity.link.claim` refuses with the same
copy. Operator commands (`identity add/link/unlink`, `devices link`, `pairing approve`) are
unaffected.

```json5 theme={"dark"}
{
  gateway: {
    webClient: {
      accountLinking: false,
    },
  },
}
```

## Reserved-name errors

A legacy config that still holds a reserved key blocks identity mutations until it is renamed:

```
Identity "constructor" is a reserved name; rename it in session.identityLinks.
```

Renaming that key in `openclaw.json` is a one-time migration fix, not part of enrollment: normal
enrollment never needs a hand edit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.