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

# Link accounts across platforms

> Verify that two accounts belong to the same person within an agent’s perspective.

Formation can recognize you across separate connector accounts within **one agent's
perspective**. Verification allows eligible private memory and history to follow
you, while keeping the original authorship of every message and memory.

## Link two accounts

1. In a private conversation with the agent on your **new account**, ask to link
   accounts or send `link accounts`.
2. The agent gives you a code. Within ten minutes, send `link CODE` in your private
   conversation with **the same agent on your established account**.
3. Formation verifies the authenticated command before model inference. The accounts
   then resolve to the established actor for eligible reads.

You must carry the code between your own sessions. The agent does not forward it,
look up a person by name, or notify a claimed account. Do not confirm a code from
someone else's session: the code proves possession of the two accounts, not a
legal identity.

No owner verification click is required. An authenticated private account can
anchor another account through this code proof. A display name, name claim, or
bare “yes” cannot link accounts. The model's `request_identity_link` tool only
starts the flow; it cannot approve a link.

## What changes

Linked accounts share a reversible read-time association. Actor labels, memory
subject matching, and `search_history(speaker=requester)` can use that association,
including for records created before linking.

Original actors, message authors, participation, memory subjects, and source
audience snapshots are not rewritten. Preferred names can follow verified links
in private conversations; a private link does not introduce a name into a group.
See [actor profiles](/runtime/actor-profiles.md).

## What remains restricted

Private continuity requires live proof for the same sole reader and a verified
direct destination. Group messages cannot start or confirm a proof. Bot messages
do not authorize linking.

Multi-reader rooms, workspace audiences, externally shared audiences, unknown
source evidence, explicit conversation restrictions, and external-tool grants
keep their existing permissions. Linking two accounts does not make your private
information available to a group or to another agent.

Memory and history access are checked again before delivery. Revoking a proof
removes its future authority; it cannot retract information already delivered.

## Unlink or recover

Send `unlink accounts` privately, or use **Unlink this account** on the actor page
as an owner. This severs that account's proof and dependent proofs. Severed accounts
must establish fresh links; they are not silently restored later.

Operators can provision an exact participant ID, such as a phone number, onto an
actor. The API is `POST /api/agents/{slug}/actors/{actorID}/identities`.
`DELETE /api/agents/{slug}/actors/{actorID}/identities/{identityID}` revokes a proof
while retaining the observed account and audit evidence.

## Limits and audit

Codes expire after ten minutes and are single-use. New accepted requests replace
older pending codes for the same claimant. Starts and confirmations are limited
by authenticated account, not by a name supplied in message text:

* Three starts per claimant in fifteen minutes.
* Ten confirmation attempts per responding account in fifteen minutes.
* Five failed confirmations against a known challenge.

A throttled start returns the same instructions with an unusable code; unsuccessful
confirmations use a common response. This avoids disclosing account-directory
information. Replays do not create a new proof or restore a revoked one.

Proof chains are scoped to one agent and bounded to 32 identities. Cycles and
cross-agent links are rejected. An actor with multiple pre-provisioned identities
cannot become a code-echo child; start from the separate new account and confirm
on a pre-provisioned account instead.

Proof digests, source message IDs, attempts, and revocations remain durable audit
records. Codes necessarily also appear in the two private transcripts. Identity
proof is separate from the agent's own external acting accounts and credentials.

Implementation: [`internal/identity` (repository)](https://github.com/TextureHQ/formation/tree/main/internal/identity)
and [`db/queries/identity_linking.sql` (repository)](https://github.com/TextureHQ/formation/blob/main/db/queries/identity_linking.sql).


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