> 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/issuance/choose-a-flow.md).

# Choose a Flow

Pick the right way to issue credentials for your use case, in two quick decisions: which flow fits, and how your users receive their one-time code.

Every issuance ends the same way: a credential signed with your Issuer Key, landing in the Holder's wallet. What differs between flows is **how and when your claim values reach the platform**, and **who starts the journey**. That choice decides what the platform stores, what you have to host, and how much you build.

There are two decisions to make, and the second one only applies to two of the flows.

## Decision 1: select a flow 🛤️

<figure><picture><source srcset="https://701364325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFaucIkpW1i4WOAQC06fj%2Fuploads%2FNOErjjV3xTh6XSuV06c4%2Fclaims_delivery_equs_dark_panel.svg?alt=media&amp;token=cc10264e-219c-4891-a809-2f5806176e7a" media="(prefers-color-scheme: dark)"><img src="https://701364325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFaucIkpW1i4WOAQC06fj%2Fuploads%2FFKeBPzTJq3AzdhAOIKN1%2Fclaims_delivery_equs_panel.svg?alt=media&amp;token=342ec5e9-c1bb-4b08-a535-9c001160b216" alt=""></picture><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th width="180">Flow</th><th>Flow 1 · Pre-authorized + push claims</th><th>Flow 2 · Authorization + pull claims</th><th>Flow 3 · Pre-authorized + pull claims</th></tr></thead><tbody><tr><td><strong>Status</strong></td><td>Fully supported</td><td>Partially supported - Issuance API ready, EQUS Wallet support in progress</td><td>Partially supported - EQUS Wallet ready, Issuance API in progress</td></tr><tr><td><strong>In one line</strong></td><td>You send claim values up front</td><td>The Holder starts, the platform asks you for the values</td><td>You trigger it, the platform asks you for the values at acceptance</td></tr><tr><td><strong>Who starts it</strong></td><td>You, from a business event - or one of your signed-in users, on your site</td><td>The Holder, from their wallet or your website, signed in or not</td><td>You, from a business event - or one of your signed-in users, on your site</td></tr><tr><td><strong>When claims are read</strong></td><td>At push time - a snapshot</td><td>At signing time - fresh</td><td>At signing time - fresh</td></tr><tr><td><strong>What the platform stores</strong></td><td>Claim values, plus the Holder's email when the platform emails the code - encrypted, scoped to your Tenant, deleted on issuance or after 5 days</td><td>Nothing</td><td>Nothing</td></tr><tr><td><strong>You host</strong></td><td>Nothing</td><td>An Attribute Provider endpoint, and an Authorization Server registered with the platform</td><td>An Attribute Provider endpoint</td></tr><tr><td><strong><code>tx_code</code></strong></td><td>Required - see Decision 2</td><td>None. The Holder signs in instead</td><td>Required - see Decision 2</td></tr><tr><td><strong>Auto-issuance</strong></td><td>Yes</td><td>No</td><td>Yes</td></tr><tr><td><strong>Protocol</strong></td><td>OID4VCI pre-authorized code</td><td>OID4VCI authorization code</td><td>OID4VCI pre-authorized code</td></tr><tr><td><strong>Effort</strong></td><td>Low - one or two API calls</td><td>Medium to high - Auth Server config, registration, a hosted endpoint</td><td>Medium - one API call, a hosted endpoint, and your own code delivery where the Holder types it</td></tr><tr><td><strong>Integration paths</strong></td><td>API, Embedded UI + API, Operator Portal</td><td>API</td><td>API, Embed UI + API</td></tr></tbody></table>

```mermaid
flowchart LR
    Q0{"Is faster integration<br/>the main priority?"}
    Q0 -->|Yes| F1
    Q0 -->|No| Q1{"Can the platform hold claim values,<br/>encrypted, until the Holder collects?"}
    Q1 -->|"Yes, a bounded window is fine"| F1["<b>Flow 1</b><br/>Pre-authorized + push claims<br/>cheapest integration"]
    Q1 -->|"No, nothing personal at rest"| Q2{"Where does the<br/>journey start?"}
    Q2 -->|"In the wallet, or with a<br/>signed-out visitor on your site"| F2["<b>Flow 2</b><br/>Authorization + pull claims<br/>you can answer denied"]
    Q2 -->|"On your side - a business event,<br/>an operator, or a signed-in user"| F3["<b>Flow 3</b><br/>Pre-authorized + pull claims<br/>nothing personal at rest"]
    style F1 fill:#e8f0fe,stroke:#4285f4
    style F2 fill:#fce8e6,stroke:#ea4335
    style F3 fill:#e6f4ea,stroke:#34a853
```

<table data-search="false"><thead><tr><th>I want...</th><th>Use</th></tr></thead><tbody><tr><td>The fastest integration - one API call, nothing to host</td><td>Flow 1</td></tr><tr><td>No personal data in platform storage at any point</td><td>Flow 2 or Flow 3</td></tr><tr><td>Claim values read fresh at the moment of issuance</td><td>Flow 2 or Flow 3</td></tr><tr><td>To be able to answer <code>denied</code> when the credential is requested</td><td>Flow 2</td></tr><tr><td>The journey to start in the wallet</td><td>Flow 2</td></tr><tr><td>The journey to start on my website, for signed-out visitors</td><td>Flow 2</td></tr><tr><td>The journey to start on my website, for signed-in users</td><td>Flow 1 or Flow 3</td></tr><tr><td>A credential to arrive with no Holder action at all</td><td>Flow 1 or Flow 3, with auto-issuance</td></tr><tr><td>Third-party wallets to work</td><td>Flow 1 or Flow 3 with <code>email</code> delivery, or Flow 2</td></tr></tbody></table>

## Decision 2 (Flows 1 and 3 only): `tx_code` delivery 📬

Both pre-authorized flows require a `tx_code` when the Offer is accepted. Flow 2 doesn't - the Holder signs in at your Authorization Server instead - so if you picked Flow 2, you're done.

For the other two, what you're really choosing is **how close the Holder is to you**, because that decides whether the code can reach them without anyone typing anything.

<figure><picture><source srcset="https://701364325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFaucIkpW1i4WOAQC06fj%2Fuploads%2FHLr0lrhZHLy9rQf6RQpb%2Fholder_ux_equs_dark_panel.svg?alt=media&amp;token=ca9ffd4b-1441-41f0-9818-6574cce96e10" media="(prefers-color-scheme: dark)"><img src="https://701364325-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFaucIkpW1i4WOAQC06fj%2Fuploads%2FgMuLgwpMQB12cV4YNT0W%2Fholder_ux_equs_panel.svg?alt=media&amp;token=df476cdc-84e6-4a00-a2c8-3f395ba518ae" alt=""></picture><figcaption></figcaption></figure>

```mermaid
flowchart LR
    S0{"Should the Offer arrive<br/>without the Holder asking?"}
    S0 -->|Yes| A["<b>Auto-issuance</b><br/>the Offer waits in Pending Offers<br/>nothing to scan, nothing to type"]
    S0 -->|"No, the Holder starts it"| S{"Which wallet, and how is<br/>the Holder signed in?"}
    S -->|"EQUS Wallet, signed in<br/>through your IdP"| P["<b>pull tx_code delivery</b><br/>the wallet fetches the code<br/>nothing to type"]
    S -->|"Any other wallet,<br/>or no login at all"| E["<b>email tx_code delivery</b><br/>the code arrives out of band<br/>the Holder types it in"]
    style A fill:#e6f4ea,stroke:#34a853
    style P fill:#e8f0fe,stroke:#4285f4
    style E fill:#fff4e5,stroke:#f9ab00
```

<table data-search="false"><thead><tr><th width="180">Journey</th><th>Auto-issuance</th><th>pull tx_code delivery</th><th>email tx_code delivery</th></tr></thead><tbody><tr><td><strong>Who the Holder is</strong></td><td>Your user, signed in to an EQUS Wallet through your IdP</td><td>Your user, signed in to an EQUS Wallet through your IdP</td><td>Anyone, with any compliant wallet</td></tr><tr><td><strong>How the code reaches them</strong></td><td>The wallet fetches it</td><td>The wallet fetches it</td><td>Flow 1: the platform emails it, or you deliver it. Flow 3: you deliver it</td></tr><tr><td><strong>What the Holder does</strong></td><td>Accepts the Offer</td><td>Scans or follows a link, then accepts</td><td>Scans or follows a link, accepts, then types the code</td></tr><tr><td><strong>In Pending Offers</strong></td><td>Yes</td><td>Yes</td><td>No</td></tr><tr><td><strong>What must be in place</strong></td><td>Your IdP registered, and an email address for the notification</td><td>Your IdP registered</td><td>Nothing</td></tr><tr><td><strong>Wallets</strong></td><td>EQUS Wallet</td><td>EQUS Wallet</td><td>Any compliant wallet</td></tr></tbody></table>

S**tart with the most seamless option your Holder qualifies for.** The closer it is, the less they have to do. If none fits, `email` always works - it assumes nothing about the Holder, and it is the only option that reaches third-party wallets, which makes it the default for issuing to the general public.

## Once you've chosen 🚀

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-bolt" style="color:$primary;">:bolt:</i></h3></td><td><strong>Flow 1: Pre-authorized + push claims</strong></td><td>The fastest integration. Three journeys, and every integration path.</td><td><a href="/docs/issuance/flow-1.md">Flow 1: Pre-authorized + push claims</a></td></tr><tr><td><h3><i class="fa-right-to-bracket" style="color:$primary;">:right-to-bracket:</i></h3></td><td><strong>Flow 2: Authorization + pull claims</strong></td><td>The Holder starts, signs in with you, and you answer at signing time.</td><td><a href="/docs/issuance/flow-2.md">Flow 2: Authorization + pull claims</a></td></tr><tr><td><h3><i class="fa-shield-halved" style="color:$primary;">:shield-halved:</i></h3></td><td><strong>Flow 3: Pre-authorized + pull claims</strong></td><td>Flow 1's shape with Flow 2's guarantee. Work in progress.</td><td><a href="/docs/issuance/flow-3.md">Flow 3: Pre-authorized + pull claims</a></td></tr></tbody></table>


---

# 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/issuance/choose-a-flow.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.