> 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/docs/presentation/flow-3/api.md). # API Run Flow 3 from your back end Your back end drives the whole thing. You create a presentation request, deliver it however suits you, receive the response on an endpoint you host, and have the platform verify it. Embed UI can still present the request to the Holder - rendering the QR code and handling the wallet hand-off - exactly as it does for [Method 1: Embed UI + API](/docs/presentation/flows-1-and-2/embed-ui-and-api.md). What changes in Flow 3 is only the return path: the response never comes back through the browser, so there is no `onSuccess` to collect it from and nothing for your front end to relay. **Before you start** you need a Verifier and a VP Schema - see [Configuration](/docs/presentation/configuration.md), which is identical for every flow - plus the push endpoint described below. {% hint style="warning" %} **Work in progress.** The push route cannot be selected on a request yet. Everything below describes the intended shape so you can design against it. {% endhint %} ### Register the endpoint the platform pushes to This is the one piece of setup unique to Flow 3, and the reason the flow is still work in progress. The platform needs to know where to push the `vp_token` once the wallet has posted it, and how to authenticate itself to you when it does. Registration is expected to work as a webhook against your Verifier. {% hint style="warning" %} **Not yet specified.** The registration call and its authentication model are still being designed. Until they land there is no way to select the push route on a request, so Flows 1 and 2 are what you can build against today. Talk to us if Flow 3 is on your roadmap. {% endhint %} What you can plan for now: * A **publicly reachable HTTPS endpoint** the platform can post to, available whenever a Holder might approve. * **Authentication of the callback**, so you can tell a genuine push from anything else that finds the URL. * **Correlation**, by the `txId` that arrives with the response, back to the session or transaction you started. * A **failure path**. The Holder has already consented by the time the push happens, so a push you can't accept is a presentation you asked for and can't collect. ### 1. Create the request One call turns a VP Schema into a request a wallet can answer. It takes the Verifier doing the asking and the schema saying what you want. {% hint style="info" icon="rectangle-api" %} All calls mentioned on this page are on the [Integration API](/docs/about-the-system/components.md). {% endhint %} The call is `POST /api/v1/{verifierId}/oid4vp/requests` with `mode` set to `direct_post.jwt`, `type` set to `vp_token`, and your `vpSchemaId`. It returns a `requestUri` and a `txId` - see Create the request for the full request and response. **Keep the `txId`.** Step 3 needs it, and it is what correlates the pushed response back to the request you made. #### Getting it to the Holder How you deliver the `requestUri` is yours to choose: * **Across devices** - render the link as a QR code for the Holder to scan. Embed UI will do this for you. * **Same device** - hand the link to the wallet directly. * **No browser at all** - deliver it however your machine-to-machine case requires. Nothing in this flow depends on a browser session, which is what makes it suitable for unattended use. ### 2. Receive the push There is no call to make. The wallet posts its encrypted response to the platform, and the platform forwards it to the endpoint you registered, in flight and without writing it to storage. What arrives is the encrypted authorization response and its `txId`. Correlate on the `txId`, and treat the body as opaque - it is encrypted under your Tenant key and your endpoint is not expected to read it. {% hint style="info" %} **Receiving a push is not the same as having a verified presentation.** The platform hands you an encrypted token; you still have to ask it to verify that token and give you the values. The push and the verification are separate calls. {% endhint %} ### 3. Verify Verification is the step that turns a token into values you can act on. Send the response and the `txId`, and get back the disclosed claims. The call is `POST /api/v1/{verifierId}/oid4vp/verify` - see Verify. The platform checks the Issuer's signature, the credential's revocation status, and that what came back actually answers what you asked. You get `verifiedClaims` - the disclosed values - and optionally `presentations`, the raw verifiable presentations keyed by credential, if you need to keep evidence rather than just the values. ### 4. Track the result Every request leaves a verification session - the same record, read the same way, as on the other flows. See [Verification Result](/docs/presentation/verification-result.md). Two of the states described there cannot occur on this flow:
StateWhy it can't occur on Flow 3
compromisedRaised by too many wrong txCode attempts. Flow 3 has no one-time code - there is no browser session to bind the response to.
neglectedRaised when a stored response is never collected and expires. Flow 3 stores nothing, so there is nothing to leave uncollected.
{% hint style="info" %} A session reaching `accepted` means the platform **pushed** the response to your endpoint. It does not mean you **received** it. If your endpoint was unavailable, the session sits at `accepted` with nothing more to collect - the Holder has consented, but the presentation is lost. Monitor for sessions that stay `accepted`. {% endhint %} ### How it works ```mermaid sequenceDiagram autonumber actor U as Holder participant W as Wallet participant TBE as Your back end participant D as Platform API participant DB as Platform storage TBE->>D: request a presentation - vp-schema-id D->>DB: create the verification session D->>TBE: presentation request TBE->>W: presentation request Note over TBE,W: however you choose to deliver it W->>W: find matching credentials on the phone U->>W: approve the presentation W->>D: direct_post.jwt carrying the vp_token D->>TBE: push the vp_token, still encrypted Note over D: not written to platform storage TBE->>D: verify the vp_token D->>DB: update the verification session D->>TBE: result + attribute values Note over D: neither the vp_token nor the claim values are stored ``` --- # 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/docs/presentation/flow-3/api.md?ask=&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.