XipID API reference

Every request goes to https://api.xipid.org with an API key of the brand, or an agent's credential, as a bearer token. The OpenAPI document describes every operation below, the errors page every code, and the changelog every version.

XipID asks the person of record whether they are present and consent, right now. A brand refers a person by its own reference for them; once they accept, it challenges them by the pairwise identifier their acceptance gave it. XipID texts them a link that carries nothing but a token, they read the request on their own phone and approve it, with a selfie when the brand's policy asks for one, or decline it, and the outcome is posted to the brand's callback URL, signed.

Agents. An org's agent calls with a credential of its own, xid_agent_live_ and 32 characters, where a brand calls with its key. It acts through one of its org's brands: it names a person by the pairwise identifier that brand holds for them, and once the person has delegated their presence to it, its challenge goes out under that brand. Each operation says who may call it, and refuses every other credential, insufficient_scope.

Versions. Every request may name a version in Xip-Version; without one it is answered in the version its org is pinned to, and every answer names the version it is in. A version is the day its contract was fixed.

Errors. A refusal is {"error": {...}} with a code to branch on, a sentence for a person, one entry in details per problem, the request's id, which X-Request-Id names too, and the page that explains the code. A code may carry members of its own.

Idempotency. Every POST that makes or changes something takes an Idempotency-Key; a retry under it is answered what the first request was, for 24 hours.

Lists. A list answers a page of items with cursors either way; starting_after and ending_before take them back.

Limits. 1,000 requests a minute per key and 2,000 requests a minute per source address; every answer says what is left in X-RateLimit-Remaining, and a refusal when to come back in Retry-After.

Growth. An answer may gain a member, and an enum a value, within a version: read what you know and carry the rest through. Every instant is RFC 3339 in UTC with milliseconds.

Challenges

A request the person of record approves or declines on their own phone, and how it closed.

• Create a challenge POST /challenges
• Read a challenge GET /challenges/{id}
• Cancel a challenge POST /challenges/{id}/cancel
• List a challenge's deliveries GET /challenges/{id}/deliveries
• Read a challenge's frames GET /challenges/{id}/frames

Subjects

The people a brand refers by its own reference for them, linked once they accept, and the face a selfie of theirs is matched to.

• Refer a person POST /subjects
• Search subjects by reference POST /subjects/search
• Read a subject GET /subjects/{id}
• Enroll a reference face PUT /subjects/{id}/reference-face
• Delete a reference face DELETE /subjects/{id}/reference-face

Events

The outcomes as they were posted to the brand's callback URLs, for 30 days.

• List events GET /events
• Read an event GET /events/{id}
• Deliver an event again POST /events/{id}/redeliver

Delegations

An agent's requests that a person delegate their presence to it, which the person accepts or declines on their XipID.

• Ask a person to delegate POST /delegations
• Read a delegation request GET /delegations/{id}