docs: add flow-definition examples - #233
Merged
Merged
Conversation
Adds six worked examples under api/openapi/endpoints/flow_definitions/examples, ordered from minimal (single-purpose password login) to full (combined login+register with password, passkey, and post-signup upsell). Each example ships a flow-definition.json plus a README with a Mermaid graph, capabilities exercised, walk-through, and gotchas. The root README indexes the ladder and cross-links to the engine's capabilities and definition-rules docs. Scope is deliberately what the engine runs today; cross-flow transitions, SSO, gates, OTP, and recovery are called out as not shown. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
@vitorbari must be a member of the zitadel team on Vercel to deploy. Learn more about collaboration on Vercel and other options here. |
Renames example 06 from combined-all-methods to combined-password-passkey so the label stays accurate as new methods (OTP, magic-link, SSO, …) land in their own examples instead of getting folded back here. Strips explicit text_key from all six examples' actions; the engine derives `<step>.action.<action>` by default (flow_state_machine.go:895-900), which is fine for documentation examples. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…vigation CTAs
Updates examples 05 and 06 to make the "duplicate" login/register entry
steps visibly distinct and to demonstrate more of the user-schema surface.
- Adds profile fields to the register branch:
- 05: register-identifier collects email + name + phoneNumber
- 06: register collects email + name; register-password collects
password + phoneNumber
All persisted by Handle (flow_on_success_create_user.go:54), which
iterates state.CollectedData and writes every non-password attribute.
- Adds explicit navigation CTAs:
- identifier exposes `register` -> register entry
- register entry exposes `login` -> identifier
Plain step transitions, not reserved outcomes. Lets users hop sub-flows
by intent instead of routing through the flip outcomes.
- Documents two sharp edges:
- HandleProvisional (passkey-register path) only persists the
identifier; profile fields collected upstream are silently dropped.
- Identifier dispatch runs before action routing; typing an email and
clicking a navigation CTA can resolve the user and pin _user_id,
then route to the register entry where create_user fails with
user_already_exists.
- Each README now has a "Step differences" table to make the distinct
fields/CTAs/downstream behavior of look-alike steps explicit.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Surface the six worked examples (and fix the broken default reference) under POST /flow_definitions so they render in the API docs alongside the request schema instead of living only as on-disk READMEs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…hema The externalValue pointed at default-human-user-schema-example.json, which never existed. Repoint to the actual file so redocly bundle resolves cleanly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
vitorbari
commented
Jun 10, 2026
| @@ -0,0 +1,37 @@ | |||
| { | |||
Contributor
Author
There was a problem hiding this comment.
One problem, this is not the actual flow-definition, it is the payload to call POST /flow_definitions. The actual flow is nested under flow_definition (line 4).
Member
There was a problem hiding this comment.
yeah, the example describes the request, not the actual model. But for me that is not really a problem. Since for the user of the api, the only thing that matters is the request.
Contributor
Author
There was a problem hiding this comment.
the body is composed of project_id, schema_uri and flow_definition.
Maybe in the future we can move the project_id and schema_uri to query params or headers, so that the body becomes only the actual flow-definition.
cc @grvijayan
…register The original shape (no fields, only the passkey_register action) hit "flow state machine: ensure user exists: user create requires attributes" because HandleProvisional only writes an attribute for a collected identifier-tagged field — with zero fields, the user row has no attributes and the repo guard rejects the insert. Collecting email on the signup step gives HandleProvisional an identifier to persist, matching the path actually exercised by the default flow and the engine's unit tests. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
vitorbari
marked this pull request as ready for review
June 10, 2026 15:03
…mber Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
vitorbari
changed the title
grvijayan
approved these changes
Jun 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds six worked examples under api/openapi/endpoints/flow_definitions/examples, ordered from minimal (single-purpose password login) to full (combined login+register with password, passkey, and post-signup upsell). Each example ships a flow-definition.json plus a README with a Mermaid graph, capabilities exercised, walk-through, and gotchas. The root README indexes the ladder and cross-links to the engine's capabilities and definition-rules docs.
Scope is deliberately what the engine runs today; cross-flow transitions, SSO, gates, OTP, and recovery are called out as not shown.
The flow definitions were also added as examples in the OpenAPI spec: