Delegations

Ask a person to delegate

POST https://api.xipid.org/delegations

Asks a person to delegate their presence to the agent, naming them by the pairwise identifier one of the agent's org's brands holds for them, with the purposes it is for and the instant the delegation would end, in the future and at most 90 days out. Nothing is sent to the person: the request waits on their XipID for 30 days, or until ends_at when that comes first, and they accept or decline it there. Asking the same person again replaces the open request. A pairwise identifier no brand of the agent's org holds is refused subject_unlinked, as one nobody holds. A retry under the same Idempotency-Key is answered the same request.

Scope: any live credential of an agent.

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.

Idempotency: takes an Idempotency-Key, which it requires: a retry under the same key is answered what the first request was, for 24 hours, and the key sent with another request is refused.

Changes: 2026-09-26: added.

Parameters

• Idempotency-Key a header, required, string, at most 512 characters

  The operation's key, 1 to 255 characters, best a UUID, in double quotes as a structured field string: a retry of the operation sends it again, and is answered what the first request was, for 24 hours.

• Xip-Version a header, optional, string, one of the values below

  The version to answer in; when absent, the version the brand's org is pinned to.

  • 2026-09-26: The first version: challenges, subjects and events, and the signed outcome.

Body

• subject object

  • pairwise_id pairwise identifier

• scopes array of object, at most 20 items

  • attribute string, one of the values below

    What the delegation lets the agent do with the person.

    • presence: Ask them to confirm it is really them, by a challenge.

  • purpose string

• ends_at instant, RFC 3339, at most 35 characters

{
  "subject": {
    "pairwise_id": "Vb3kQ9xR2mTz7LpW4nYc8d"
  },
  "scopes": [
    {
      "attribute": "presence",
      "purpose": "wire_approval"
    }
  ],
  "ends_at": "2027-01-31T00:00:00-05:00"
}

Answers

201 Created

The request, waiting on the person. Location names it.

Its headers: X-Request-Id, Xip-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Location.

• id ULID

• status string, one of the values below

  Where the request is: waiting on the person, or how it closed; every value but the first is final.

  • pending: Waiting on the person, who sees it on their XipID.
  • accepted: The person accepted: the delegation holds until ends_at, unless they revoke it first.
  • declined: The person declined, and nothing was granted.
  • expired: No answer came by expires_at: 30 days after the request, or ends_at when that came first.
  • replaced: The agent asked the person again, and the newer request took its place.
  • canceled: The agent was retired.

• subject object

  • pairwise_id pairwise identifier

• scopes array of object

  • attribute string, one of the values below

    What the scope lets the brand do with the person.

    • presence: Ask them to confirm it is really them, by a challenge.
    • name: See their name.
    • date_of_birth: See their date of birth.
    • email: See their email address.
    • phone: See their phone number.
    • address: See their address.
    • tier: See their verification tier.
    • ssn_match: Check that a Social Security number the brand holds is theirs.

  • purpose string

• ends_at instant, RFC 3339

• expires_at instant, RFC 3339

• created_at instant, RFC 3339

• decided_at instant, RFC 3339, optional

{
  "id": "01JD2RE0F2H4K6M8N0P2Q4S6T8",
  "status": "pending",
  "subject": {
    "pairwise_id": "Vb3kQ9xR2mTz7LpW4nYc8d"
  },
  "scopes": [
    {
      "attribute": "presence",
      "purpose": "wire_approval"
    }
  ],
  "ends_at": "2027-01-31T05:00:00.000Z",
  "expires_at": "2026-12-18T15:30:12.408Z",
  "created_at": "2026-11-18T15:30:12.408Z"
}

Errors

• json_invalid, 400: The request body is not valid JSON.
• parameter_missing, 400: The request lacks a required parameter.
• parameter_invalid, 400: The request contains invalid parameters.
• parameter_unknown, 400: The request contains a parameter this route does not take.
• idempotency_key_missing, 400: This route requires an Idempotency-Key header.
• version_invalid, 400: Xip-Version names no released version of this API.
• authentication_required, 401: Authentication is required.
• authentication_failed, 401: The credential is invalid, expired or revoked.
• insufficient_scope, 403: The credential does not allow this operation.
• idempotency_key_in_use, 409: The first request with this Idempotency-Key is still running.
• content_too_large, 413: The request body is larger than this route accepts.
• media_type_unsupported, 415: This route does not accept that Content-Type.
• idempotency_key_reused, 422: This Idempotency-Key was used for a different request.
• subject_unlinked, 422: The pairwise identifier names no person linked to this brand, or to a brand of this agent's org.
• rate_limit_exceeded, 429: Too many requests; try again later.
• internal_error, 500: Something went wrong on our side.
• service_unavailable, 503: The service is temporarily unavailable.