---
title: "Hand off an x401 Verifiable Credential Presentation request"
method: POST
path: "/verifiable-credentials/v1/x401-handoff"
tags: ["OID4VP"]
---

# Hand off an x401 Verifiable Credential Presentation request

`POST /verifiable-credentials/v1/x401-handoff`

## Request

- Base URL: `https://api.proof.com`
- URL: `https://api.proof.com/verifiable-credentials/v1/x401-handoff`
- Auth: none declared

Accepts an x401 payload (https://x401.proof.com/spec/latest/#x401-payload) that wraps a Digital Credentials API request (https://www.w3.org/TR/digital-credentials/#DC-API) using the `openid4vp-v1-signed` protocol, and processes it as an OID4VP presentation request for the End-User identified by the `login_hint` claim of the signed request object. When the request carries a Proof access token issued to an End-User in the `Authorization: Bearer` header, that End-User is used instead of `login_hint`, and an invalid token is rejected with `invalid_token`. 

The real OID4VP request is carried inside the signed request object at `credential_requirements.digital.requests[0].data.request`: a compact JWS with `typ` header `oauth-authz-req+jwt`, signed with ES256 by a key whose JWK is registered on your OAuth Application. Your `client_id` is conveyed by the request object's `iss`/`client_id` claims. Its `response_mode` must be `dc_api`. It must carry an `exp` claim at most one hour ahead and a unique `jti` claim; a request object is accepted once. 

On success Proof returns a `request_uri` suitable for presenting to the End-User via their AI agent. Supply a top-level `return_uri` to use the x401 intermediary return channel (https://x401.proof.com/spec/latest/#return-channel); its origin must appear in the request object's `expected_origins`.

AI agents that cannot receive the presentation themselves omit `return_uri` and send an access token with the `agentic` scope. This requires the request object's `expected_origins` to be the agents trust list. Proof then also returns a `result_polling_uri` the agent polls with the same access token.

## Headers

- `Authorization` string

## Request body

- X401Payload
  - `credential_requirements` object, required
    - `digital` object, required
      - `requests` object[], required: Must contain exactly one Digital Credentials API request.
        - `protocol` 'openid4vp-v1-signed', required: The DC API protocol. Only the signed variant `openid4vp-v1-signed` is supported.
        - `data` object, required
          - `request` string, required: The signed OID4VP request object (a JAR), as a compact JWS. It MUST have `typ` header `oauth-authz-req+jwt`, be signed with ES256 by a key whose JWK is registered on your OAuth Application, and carry the OID4VP request claims: `iss` (equal to `client_id`), `aud` (the Proof presentation issuer), `client_id`, `response_type` (`vp_token`), `response_mode` (`dc_api`), `scope`, `login_hint`, and `nonce`. For the intermediary flow, also include `expected_origins`. To let AI agents poll for the result instead, set `expected_origins` to exactly the agents trust list (`/.well-known/agents-trust-list` on this API host) and omit `response_uri`.
  - `return_uri` string: Optional. Enables the x401 intermediary return channel (https://x401.proof.com/spec/latest/#return-channel). When present, Proof POSTs the Verifiable Credential Presentation to this URI instead of the request object's `response_uri`. Its origin must be listed in the request object's `expected_origins`, and the request object must not itself specify a `response_uri`. Omit it when the request object's `expected_origins` is the agents trust list: Proof then keeps the result for the calling agent to poll at `result_polling_uri`.

## Response `201`

Created

- X401HandoffResponse
  - `request_uri` string: A link to the Proof-hosted flow where the End-User authorizes the Verifiable Credential Presentation.
  - `result_polling_uri` string: Only present when the request object's `expected_origins` is the agents trust list and `return_uri` is omitted. Poll this URI with the same `agentic` access token to retrieve the Verifiable Credential Presentation once the End-User completes the flow.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized

---

[API](https://skmtc.dev/proof/apis/proof-verifiable-credentials-api-specification.md) - [All operations](https://skmtc.dev/proof/apis/proof-verifiable-credentials-api-specification/llms.txt) - [OpenAPI document](https://skmtc.dev/proof/apis/proof-verifiable-credentials-api-specification/revisions/09d16a4195bc?raw)