Skip to content

docs: document oauth2_login_request in courier template data #2669

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vinckr merged 2 commits into from
Jul 13, 2026
+46 −0
Merged

docs: document oauth2_login_request in courier template data #2669

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
edb75cd
docs: document oauth2_login_request in courier template data
hperl Jul 9, 2026
75af697
chore: format
vinckr Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/kratos/emails-sms/05_custom-email-templates.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,23 @@ In addition to the variables listed for each template, every template can access
[Transient payload in templates](#transient-payload-in-templates)) and `RequestURL` (the URL of the flow request that triggered
the email).

The `login_code.valid`, `registration_code.valid`, `verification_code.valid`, and `verification.valid` templates can also access
`OAuth2LoginRequest` when the flow was started through an OAuth2 login challenge, for example when a user signs in to an OAuth2
client. Because Ory resolves this value server-side, it can't be forged by the end user. Use it to brand messages per OAuth2
client instead of the end-user-controlled transient payload:

| Variable | Description |
| -------------------------------------- | ------------------------------------------------ |
| `OAuth2LoginRequest.Challenge` | the OAuth2 login challenge that started the flow |
| `OAuth2LoginRequest.Client.ClientID` | the OAuth2 client ID |
| `OAuth2LoginRequest.Client.ClientName` | the human-readable name of the OAuth2 client |
| `OAuth2LoginRequest.Client.ClientURI` | the URL of the OAuth2 client's homepage |
| `OAuth2LoginRequest.Client.LogoURI` | the URL of the OAuth2 client's logo |
| `OAuth2LoginRequest.Client.Metadata` | the metadata set on the OAuth2 client |

For example: `{{ if .OAuth2LoginRequest }}{{ .OAuth2LoginRequest.Client.ClientName }}{{ end }}`. The variable is unset when the
flow wasn't started through an OAuth2 login challenge.

```mdx-code-block
<Tabs groupId="email-templates">
<TabItem value="recovery_code" label="Recovery (via code)" default>
Expand Down
29 changes: 29 additions & 0 deletions docs/kratos/self-hosted/03_mail-courier-http.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,12 +64,41 @@ available through a `ctx` object. `recipient` will always be the email address o
- to
- verification_url
- identity
- oauth2_login_request (optional)
- verification_code_invalid
- to
- verification_code_valid
- to
- verification_code
- identity
- oauth2_login_request (optional)
- login_code_valid
- to
- login_code
- identity
- oauth2_login_request (optional)
- registration_code_valid
- to
- registration_code
- traits
- oauth2_login_request (optional)

The `oauth2_login_request` field is only present when the flow was started through an OAuth2 login challenge, for example when a
user signs in to an OAuth2 client. Because Ory resolves it server-side, it can't be forged by the end user. Use it to brand
messages per OAuth2 client:

```json
"oauth2_login_request": {
"challenge": "...",
"client": {
"client_id": "...",
"client_name": "...",
"client_uri": "...",
"logo_uri": "...",
"metadata": {}
}
}
Comment thread
hperl marked this conversation as resolved.
```

A universal Jsonnet template that works with all flows, would look like this:

Expand Down
Loading