Delegations

Read a delegation request

GET https://api.xipid.org/delegations/{id}

The agent's request as it stands, and as it closed once it has: accepted, declined, expired, replaced by a newer request, or canceled when the agent was retired. An agent reads its own requests alone.

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: a read, safe to repeat.

Changes: 2026-09-26: added.

Parameters

• id in the path, required, ULID

  XipID's id for the delegation request.

• 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.

Answers

200 OK

The request as it stands.

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

• 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": "accepted",
  "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",
  "decided_at": "2026-11-18T15:47:31.902Z"
}

Errors

• json_invalid, 400: The request body is not valid JSON.
• parameter_invalid, 400: The request contains invalid parameters.
• parameter_unknown, 400: The request contains a parameter this route does not take.
• 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.
• resource_not_found, 404: No such resource.
• 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.
• 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.