Identify Handle

Server URLloading...

POST

/v1/identify

Send

Authorization

Body

Says to whom the handle of a browser belongs. The body has one of three forms.

{ handle, participant }: this browser belongs to the participant. Send it once, at the identity moment (the creation of the account or the group), when the fact that counts comes later, for example a signup at email verification. A signup sent at account creation can send the handle in identify instead. Do not identify at sign-in, verification, or account linking. The call creates the participant when the Project does not have it.

{ handle, reference }: this browser belongs to the person of a flow that starts before the account exists and can end on another device or in a hosted login, such as a magic link or a one-time code. reference.key is your key of the flow, unique in the Project and bound to its challenge (for example a digest of the magic-link token); a key is never used again. The call that names an unknown key creates its reference, which expires at reference.expiresAt: after the receipt and at most 90 days after it; the default is 24 hours after it. An expired reference gets 409.

{ reference, participant }: the account of the flow exists. The reference resolves once to the participant, and the handles identified to it then belong to the participant. The same participant again returns the first result; another participant, or a reference that expired before it resolved, gets 409. A key that no handle named yet is created resolved, so the two calls can come in either order.

A handle is identified once: the same target again returns the first identification, and another target gets 409. An unknown handle, or a handle of another Project, gets 404. observedAt is the time of the identity moment; the default is the receipt. A caller clock can run ahead: an observedAt up to 5 minutes after the receipt records the receipt, and a later one gets 400. The click window of a handle ends at its identification, also when its reference resolves later. A fact uses only the identifications and resolves that RefRef received at or before the fact; a fact never waits for one.

Response BodyCopy Anchor Link

curl -X POST "https://example.com/v1/identify" \  -H "Content-Type: application/json" \  -d '{    "projectId": "string",    "handle": "string",    "participant": {      "kind": "individual",      "externalId": "string"    }  }'

{  "success": true,  "identificationId": "string",  "handle": "string",  "identifiedAt": "string",  "participantId": "string"}