> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/api/integration-api/oid4vp.md).

# Oid4Vp

## Create multiple Authorization Requests (web and mobile)

> Create multiple Authorization Requests by Verifier based on VP Schema pointing to default Embed UI

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Integration API Documentation","version":"0.1.2"},"tags":[{"name":"Oid4Vp","description":""}],"security":[{"sp":[]},{"tenant":[]},{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"CreateMultiRequestRequest":{"type":"object","properties":{"vpSchemaId":{"type":"string","description":"VP schema unique ID"},"encrypted":{"type":"boolean","description":"Whether the generated presentation requests should be encrypted"},"modes":{"type":"array","description":"Presentation channels to generate an authorization request for.","items":{"type":"string","enum":["web","mobile","dcApi"]}},"verifierWebUrl":{"type":"string","description":"URL of the verifier web page that will display the presentation request."},"intendedUseId":{"type":"string","description":"Intended use to create this request under. Required once the Verifier has registered one; its registration certificate is emitted to the Wallet as a `verifier_info` entry."}},"required":["vpSchemaId","modes","verifierWebUrl"]},"CreateMultiRequestResponse":{"type":"object","properties":{"web":{"description":"Authorization request generated for the web presentation channel.","allOf":[{"$ref":"#/components/schemas/CreateAuthorizationRequestResponse"}]},"mobile":{"description":"Authorization request generated for the mobile presentation channel.","allOf":[{"$ref":"#/components/schemas/CreateAuthorizationRequestResponse"}]},"dc":{"description":"Authorization request generated for the Digital Credentials API channel.","allOf":[{"$ref":"#/components/schemas/CreateAuthorizationRequestResponse"}]}},"required":["web"]},"CreateAuthorizationRequestResponse":{"type":"object","properties":{"requestUri":{"type":"string","description":"URI from which the wallet can fetch the full authorization request object."},"txId":{"type":"string","description":"Transaction unique ID"}},"required":["requestUri","txId"]}}},"paths":{"/api/v1/{verifierId}/oid4vp/requests/multi":{"post":{"description":"Create multiple Authorization Requests by Verifier based on VP Schema pointing to default Embed UI","operationId":"Oid4VpController_createMultiRequest_api/v1","parameters":[{"name":"verifierId","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMultiRequestRequest"}}}},"responses":{"200":{"description":"When multiple Authorization Requests are created successfully, the web, mobile and dc request uris and corresponding txIds are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMultiRequestResponse"}}}},"400":{"description":"When the Verifier uses x509_san_dns and the response URI FQDN does not match its Client Identifier."},"404":{"description":"- When no VP Schema exists with such id.\n- When no verifier found."},"422":{"description":"- When the Verifier uses an x509 Client Identifier Prefix and no access certificate is active.\n- When the active access certificate has been revoked, is expired or not yet valid, or carries no dNSName SAN naming the protocol host.\n- When the SDK refuses the x509 Client Identifier, because the certificate chain, the identifier and the signing key do not agree."}},"summary":"Create multiple Authorization Requests (web and mobile)","tags":["Oid4Vp"]}}}}
```

## Create Authorization Request

> Create Authorization Request by Verifier based on VP Schema

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Integration API Documentation","version":"0.1.2"},"tags":[{"name":"Oid4Vp","description":""}],"security":[{"sp":[]},{"tenant":[]},{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"CreateAuthorizationRequestRequest":{"type":"object","properties":{"mode":{"type":"string","description":"Mechanism used by the wallet to deliver the authorization response. Only encrypted modes are supported.","enum":["direct_post.jwt","dc_api.jwt"]},"type":{"type":"string","description":"Type of authorization response requested from the wallet.","enum":["vp_token","vp_token id_token"]},"redirectUri":{"type":"string","description":"URL the wallet redirects the holder to after submitting the response."},"expectedOrigins":{"description":"Web origins (http or https) allowed to complete a DC API presentation for this request. Each value is reduced to its origin: scheme, host and non-default port.","type":"array","items":{"type":"string"}},"vpSchemaId":{"type":"string","description":"VP schema unique ID"},"verifierWebUrl":{"type":"string","description":"URL of the verifier web page that will display the presentation request."},"transactionData":{"description":"Transaction data items the wallet must sign over as part of the response.","type":"array","items":{"$ref":"#/components/schemas/DelegateTransactionDataItem"}},"intendedUseId":{"type":"string","description":"Intended use to create this request under. Required once the Verifier has registered one; its registration certificate is emitted to the Wallet as a `verifier_info` entry."}},"required":["mode","type","vpSchemaId"]},"DelegateTransactionDataItem":{"type":"object","properties":{"type":{"type":"string","description":"Type of transaction data item.","enum":["delegate"]},"credentialInputIndex":{"type":"number","description":"Index of the credential input this transaction data item applies to."},"format":{"type":"string","description":"Delegated SD-JWT format the disclosed payload claims are issued in.","enum":["dSD-JWT","dSD-JWT+KB"]},"delegateJwk":{"type":"object","description":"JWK of the delegate key that the disclosed payload claims are bound to."},"payloadClaims":{"type":"object","description":"Claims disclosed to the verifier via the delegated presentation."}},"required":["type","credentialInputIndex","format","payloadClaims"]},"CreateAuthorizationRequestResponse":{"type":"object","properties":{"requestUri":{"type":"string","description":"URI from which the wallet can fetch the full authorization request object."},"txId":{"type":"string","description":"Transaction unique ID"}},"required":["requestUri","txId"]}}},"paths":{"/api/v1/{verifierId}/oid4vp/requests":{"post":{"description":"Create Authorization Request by Verifier based on VP Schema","operationId":"Oid4VpController_createAuthorizationRequest_api/v1","parameters":[{"name":"verifierId","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAuthorizationRequestRequest"}}}},"responses":{"200":{"description":"When Authorization Request is created successfully. The uri for the authorization request and corresponding txId is returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAuthorizationRequestResponse"}}}},"400":{"description":"When the Verifier uses x509_san_dns and the response URI FQDN does not match its Client Identifier."},"404":{"description":"- When no VP Schema exists with such id.\n- When no verifier found."},"422":{"description":"- When the Verifier uses an x509 Client Identifier Prefix and no access certificate is active.\n- When the active access certificate has been revoked, is expired or not yet valid, or carries no dNSName SAN naming the protocol host.\n- When the SDK refuses the x509 Client Identifier, because the certificate chain, the identifier and the signing key do not agree."}},"summary":"Create Authorization Request","tags":["Oid4Vp"]}}}}
```

## \[Experimental] Create AP2 mandate request

> Create an OID4VP authorization request carrying one or more AP2 mandates, without needing to construct a DCQL query or handle dSD-JWT delegation directly.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Integration API Documentation","version":"0.1.2"},"tags":[{"name":"Oid4Vp","description":""}],"security":[{"sp":[]},{"tenant":[]},{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"CreateMandateRequestRequest":{"type":"object","properties":{"mode":{"type":"string","description":"Mechanism used by the wallet to deliver the authorization response. Only encrypted modes are supported.","enum":["direct_post.jwt","dc_api.jwt"]},"vpSchemaId":{"type":"string","description":"The VP Schema to build the DCQL query against. Tenants create their own."},"mandates":{"description":"One or more AP2 mandates. All mandates must be Open, or all must be Closed — mixing is not supported.","type":"array","items":{"$ref":"#/components/schemas/Ap2BaseMandate"}},"agentKey":{"description":"Public JWK confirmation key for the delegate, embedded as cnf on Open mandates. Required when any mandate is Open; forbidden when every mandate is Closed.","allOf":[{"$ref":"#/components/schemas/PublicJWK"}]},"redirectUri":{"type":"string","description":"Same-device redirect target after the delegating wallet responds."},"verifierWebUrl":{"type":"string","description":"Web hand-off / QR surface the delegating human lands on."},"expectedOrigins":{"description":"Web origins (http or https) expected for a Digital Credentials API (DC API) response mode.","type":"array","items":{"type":"string"}}},"required":["mode","vpSchemaId","mandates"]},"Ap2BaseMandate":{"type":"object","properties":{"vct":{"enum":["mandate.checkout.open.1","mandate.checkout.1","mandate.payment.open.1","mandate.payment.1"],"type":"string","description":"Mandate type discriminator (the verifiable credential type)."},"exp":{"type":"number","minimum":0,"description":"Unix epoch. Defaults to iat + the configured mandate TTL when omitted."}},"required":["vct"]},"PublicJWK":{"type":"object","properties":{"kty":{"type":"string","description":"JWK key type, naming the key family the other members belong to."},"crv":{"type":"string","description":"Cryptographic curve the key uses. Present for EC and OKP key types."},"x":{"type":"string","description":"Base64url-encoded x coordinate. Present for EC and OKP key types; for OKP it carries the whole public key."},"y":{"type":"string","description":"Base64url-encoded y coordinate. Present for EC key types only."},"n":{"type":"string","description":"Base64url-encoded modulus. Present for RSA key types only."},"e":{"type":"string","description":"Base64url-encoded public exponent. Present for RSA key types only."},"use":{"type":"string","enum":["sig","enc"],"description":"JWK public key use."},"key_ops":{"description":"JWK key operations.","type":"array","items":{"type":"string"}},"alg":{"type":"string","description":"Cryptographic algorithm intended for use with this key."},"kid":{"type":"string","description":"JWK key ID, identifying the key within the JWK itself."},"x5u":{"type":"string","format":"uri","description":"URL of the X.509 certificate chain for this key."},"x5c":{"description":"X.509 certificate chain for this key.","type":"array","items":{"type":"string"}},"x5t":{"type":"string","description":"X.509 certificate SHA-1 thumbprint."},"x5t#S256":{"type":"string","description":"X.509 certificate SHA-256 thumbprint."}},"required":["kty"]},"CreateMandateRequestResponse":{"type":"object","properties":{"requestUri":{"type":"string","description":"The OID4VP request URI to render as a QR code or embed in a deep link for the delegating human."},"txId":{"type":"string","description":"Correlation id for the eventual verification call."}},"required":["requestUri","txId"]}}},"paths":{"/api/v1/{verifierId}/oid4vp/requests/ap2":{"post":{"description":"Create an OID4VP authorization request carrying one or more AP2 mandates, without needing to construct a DCQL query or handle dSD-JWT delegation directly.","operationId":"Oid4VpController_createMandateRequest_api/v1","parameters":[{"name":"verifierId","required":true,"in":"path","description":"The verifier to create the mandate request against.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMandateRequestRequest"}}}},"responses":{"200":{"description":"When the AP2 mandate request is created successfully. The uri for the authorization request and corresponding txId is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMandateRequestResponse"}}}},"400":{"description":"When mandate content fails validation against its vct schema, mixes open and closed mandates, is missing a required agentKey, an Open Checkout Mandate is missing a checkout.line_items constraint, a closed Checkout/Payment mandate pair does not link correctly."},"404":{"description":"When no VP Schema exists with such id."}},"summary":"[Experimental] Create AP2 mandate request","tags":["Oid4Vp"]}}}}
```

## Get Authorization Response

> Retrieve Authorization Response by response code and txId

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Integration API Documentation","version":"0.1.2"},"tags":[{"name":"Oid4Vp","description":""}],"paths":{"/api/v1/oid4vp/responses":{"get":{"description":"Retrieve Authorization Response by response code and txId","operationId":"Oid4VpController_getAuthorizationResponse_api/v1","parameters":[{"name":"responseCode","required":false,"in":"query","description":"Code returned by the wallet to fetch the authorization response.","schema":{"type":"string"}},{"name":"txCode","required":false,"in":"query","description":"Transaction code used to authorize retrieval of the response.","schema":{"type":"string"}},{"name":"txId","required":true,"in":"query","description":"Transaction unique ID","schema":{"type":"string"}}],"responses":{"200":{"description":"When Authorization Response is resolved correctly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAuthorizationResponseResponse"}}}}},"summary":"Get Authorization Response","tags":["Oid4Vp"]}}},"components":{"schemas":{"GetAuthorizationResponseResponse":{"type":"object","properties":{"vpToken":{"type":"object","description":"Plain verifiable presentation token. Only set when the response is not encrypted."},"jwe":{"type":"string","description":"Encrypted JWE containing the authorization response. Only set when the response is encrypted."},"type":{"type":"number","description":"Indicates whether the authorization response is plain or encrypted."},"transactionDataResponse":{"type":"object","description":"Hashes of the transaction data items the wallet signed over."}},"required":["type"]}}}}
```

## Get one-time txCode for Authorization Response

> Exchange responseCode on OTP txCode

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Integration API Documentation","version":"0.1.2"},"tags":[{"name":"Oid4Vp","description":""}],"paths":{"/api/v1/oid4vp/tx-codes":{"get":{"description":"Exchange responseCode on OTP txCode","operationId":"Oid4VpController_getTxCode_api/v1","parameters":[{"name":"responseCode","required":true,"in":"query","description":"Code returned by the wallet to fetch the pending tx-code.","schema":{"type":"string"}}],"responses":{"200":{"description":"When txCode was retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTxCodeResponse"}}}}},"summary":"Get one-time txCode for Authorization Response","tags":["Oid4Vp"]}}},"components":{"schemas":{"GetTxCodeResponse":{"type":"object","properties":{"txCode":{"type":"string","description":"Transaction code the holder must present to redeem the offer. Exchanged for txId for real Cross-device flow."},"txCodeExpireAt":{"format":"date-time","type":"string","description":"Date and time the transaction code expires at."},"verifierWebUrl":{"type":"object","description":"URL of the verifier web page that displayed the presentation request."}},"required":["txCode","txCodeExpireAt","verifierWebUrl"]}}}}
```

## Verify Presentation

> Verify submitted Authorization Response and return verification result

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Integration API Documentation","version":"0.1.2"},"tags":[{"name":"Oid4Vp","description":""}],"security":[{"sp":[]},{"tenant":[]},{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"VerifyPresentationRequest":{"type":"object","properties":{"authResponse":{"description":"Authorization response returned by the wallet containing the presentation.","allOf":[{"$ref":"#/components/schemas/AuthResponse"}]},"txId":{"type":"string","description":"Transaction unique ID"},"origin":{"type":"string","description":"Web origin (http or https) the presentation response was submitted from."}},"required":["authResponse","txId"]},"AuthResponse":{"type":"object","properties":{"vpToken":{"type":"object","description":"Plain verifiable presentation token. Mutually exclusive with jwe."},"jwe":{"type":"string","description":"Encrypted JWE containing the authorization response. Mutually exclusive with vpToken."},"transactionDataResponse":{"type":"object","description":"Hashes of the transaction data items the wallet signed over."},"type":{"type":"number","description":"Indicates whether the authorization response is plain or encrypted."}},"required":["type"]},"VerifyPresentationResponse":{"type":"object","properties":{"verifiedClaims":{"type":"object","description":"Claims disclosed and verified from the holder-presented credential."},"presentations":{"type":"object","description":"Raw verifiable presentations submitted by the holder, keyed by credential."}},"required":["verifiedClaims"]}}},"paths":{"/api/v1/{verifierId}/oid4vp/verify":{"post":{"description":"Verify submitted Authorization Response and return verification result","operationId":"Oid4VpController_verifyPresentation_api/v1","parameters":[{"name":"verifierId","required":true,"in":"path","description":"Verifier unique ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyPresentationRequest"}}}},"responses":{"200":{"description":"When Presentation is verified successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyPresentationResponse"}}}},"400":{"description":"- When the session advertised a response encryption key but the Authorization Response was sent in plain, encrypted under a foreign key, or carried a malformed JWE.\n- When the origin supplied for a DC API verification is not one the Authorization Request declared in its expected origins."},"409":{"description":"When the verification session was verified, failed, deleted or expired by another request while this presentation was being verified."},"422":{"description":"When the access certificate the verification session was created under can no longer be resolved, or has since been revoked."},"500":{"description":"When a DC API verification session was stored without the expected origins its Authorization Request declared."}},"summary":"Verify Presentation","tags":["Oid4Vp"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.toolkit.equs.ai/api/integration-api/oid4vp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.