I'd be happy to explain these concepts in Ory's authentication flows: ## TransientPayload TransientPayload is a feature that allows you to pass additional temporary data along with certain self-service flows without permanently storing it. It's available in various authentication flows including login, registration, and settings flows. The transient payload: - Must be a valid JSON object - Is passed to any webhooks triggered by the flow - Is not persisted by Ory in the long term - Can be accessed in email templates using

{{index .TransientPayload "key_name"}}

For example, in a registration flow, you can include transient data like this:

json {   "method": "password",   "password": "secure-password",   "traits": {     "email": "<mailto:user@example.com|user@example.com>"   },   "transient_payload": {     "consents": [       {         "id": "cookies",         "given": true,         "date": "2023-03-02"       }     ]   } }

This is particularly useful for passing data that should be processed by webhooks but doesn't need to be stored permanently in Ory's identity system [Possibility to define complex data types in the metadata of identity](https://github.com/ory/network/issues/187). ## UpstreamParameters UpstreamParameters are parameters passed to upstream identity providers when using social login methods like OpenID Connect (OIDC). These are optional and depend on what the upstream provider supports. Common supported parameters include: -

login_hint

(string): Suppresses the account chooser and pre-fills the email box or selects the proper session -

hd

(string): Limits the login/registration process to a specific Google Organization (e.g.,

<http://mycollege.edu|mycollege.edu>

) -

prompt

(string): Specifies whether the Authorization Server prompts the user for reauthentication and consent (e.g.,

select_account

) These parameters can be included in login and registration flows when using OIDC methods [Kratos API Reference](https://www.ory.sh/docs/kratos/reference/api). ## AdditionalProperties Based on the knowledge sources provided, there isn't specific information about "AdditionalProperties" in the context of Ory authentication flows. However, there is a mention in one of the GitHub issue comments suggesting that additionalProperties on metadata could be used as a schema-less and flexible way to model data. Without more context from the knowledge sources, I can't provide detailed information about this specific concept in Ory.

To access values from TransientPayload in Ory, there are different ways depending on where you're trying to retrieve the data: ## In Email Templates You can access TransientPayload values in email templates using the Go template syntax:

{{index .TransientPayload "example_key"}}

For example, if you passed a transient payload with an

example_key

field:

transient_payload: {   example_key: "This is an example value" }

You can use it in your email template like this:

html <p>Transient Payload: {{index .TransientPayload "example_key"}}</p>

You can even use conditional logic based on transient payload values:

html {{- if eq (index .TransientPayload "lang") "foo" -}}   FOO {{- else -}}   BAR {{- end -}}

[Customizing template content for specific users](https://www.ory.sh/docs/kratos/emails-sms/custom-email-templates#transient-payload-in-templates) ## In Webhooks The TransientPayload is passed to any webhooks triggered by the flow. In your webhook handler, you'll receive the transient payload as part of the request body. You can extract and process this data according to your application's needs. For example, in a post-registration webhook, the transient payload would be included in the webhook request body, allowing your webhook handler to access any data you passed during the registration process. ## Important Notes 1. TransientPayload is temporary and not persisted by Ory in the long term 2. It must be a valid JSON object 3. It's available in various flows including login, registration, and settings flows 4. It's primarily designed to pass data to webhooks and email templates without storing it permanently The TransientPayload feature is particularly useful for passing additional information that doesn't need to be stored as part of the identity but is needed for processing during the authentication flow.

I'll explain when flows are marked as success in Ory Identities (Kratos) and how the success state works. ## When is a flow marked as success? A flow is marked as success when the form payload is valid and all required validations pass. The specific behavior depends on the type of flow: 1. Login Flow: Marked as success when credentials are validated correctly. The response includes a session token/cookie and the user's identity information. 2. Registration Flow: Marked as success when a new identity is successfully created. The response includes the newly created identity and potentially a session if auto-login is enabled. 3. Settings Flow: Marked as success when profile updates are successfully applied. The response includes a success message and the updated identity information. As shown in the documentation, successful flows typically include a state field with the value "success":

json {   "identity": {     "id": "5b23b651-c186-4398-8717-f15ac72cbc7e",     "schema_id": "default",     "schema_url": "<https://playground.projects.oryapis.com/schemas/default>",     "traits": {       "email": "<mailto:user@example.com|user@example.com>"     },     // ...   },   "state": "success" }

[Kratos Self-service Flows: Settings and profile updates](https://www.ory.sh/docs/kratos/self-service/flows/user-settings#client-side-browser-clients) ## How flows are processed to reach success state The flow process typically follows these steps: 1. The flow is initiated 2. The user completes the form 3. The form is submitted to Ory Identities 4. Ory validates the payload 5. If validation passes, the flow completes with success As the documentation states: > "If the form payload is valid, the flow completes with a success. The result here depends on the flow itself..." [Kratos Self-service flows: Form submission and payload validation](https://www.ory.sh/docs/kratos/self-service#form-submission-and-payload-validation) ## Manually making a flow succeed You cannot manually mark a flow as success without going through the proper validation process. Ory Identities handles the flow state internally based on the validation results. To complete a flow successfully, you need to: 1. Initialize the appropriate flow (login, registration, settings, etc.) 2. Submit valid data to the flow's action URL 3. Ensure all required fields are provided and valid For example, to complete a login flow successfully:

curl -s -X POST -H "Accept: application/json" -H "Content-Type: application/json" \     -d '{"identifier": "<mailto:user@example.com|user@example.com>", "password": "password", "method": "password"}' \     "<https://playground.projects.oryapis.com/self-service/login?flow=<flow-id>>"

If the credentials are valid, Ory will automatically mark the flow as successful and return the appropriate response. The success state is determined by Ory's internal validation logic and cannot be manually overridden as it's a security feature to ensure proper authentication and authorization.

I'll explain how an OIDC (OpenID Connect) flow is marked as success in Ory. ## OIDC Flow Success in Ory In Ory, an OIDC flow is marked as success when the user successfully authenticates with the external identity provider and all required validations pass. The process follows these general steps: 1. The user initiates the OIDC authentication flow 2. They are redirected to the external identity provider (like Google, GitHub, etc.) 3. After authenticating with the provider, they are redirected back to Ory 4. Ory validates the response from the provider 5. If validation passes, the flow is marked as successful For registration flows using OIDC, it's important to note that you should enable the session hook to provide a good user experience:

yaml selfservice:   flows:     registration:       after:         oidc:           hooks:             - hook: session # Always enable this for oidc flows or the user experience suffers significantly!

As the documentation states: "It's very important to add the 'session' hook to the after

oidc

registration hooks. Otherwise your users need to use the login flow again to be able to get a session." [Kratos Self-service Flows: Registration](https://www.ory.sh/docs/kratos/self-service/flows/user-registration#successful-registration) ## Success Response When an OIDC flow completes successfully: 1. For browser-based flows: The user is redirected to the configured redirect URL with a session cookie set 2. For API clients: A JSON response is returned containing the session information and identity details The success state is indicated in different ways depending on the flow type: - For login flows: The response includes a session token/cookie and the user's identity - For registration flows: The response includes the newly created identity and a session if the session hook is enabled In some cases, redirect loops can occur after successful OIDC registration. This issue is documented and can be resolved as mentioned in the GitHub discussion: [OIDC + passkey registration flow with username as identity](https://github.com/ory/kratos/discussions/3987). The OIDC flow success is handled automatically by Ory's internal validation logic based on the response from the identity provider, and you cannot manually override this process as it's a security feature to ensure proper authentication.

Based on the knowledge sources provided, I can explain how to use transient payload in an OIDC flow with Ory. To pass transient payload data in an OIDC flow, you can include it when updating the login flow. The transient payload is an optional field that can be included in various authentication methods, including OIDC. When using the OIDC method for login, you would include the transient_payload field in your request body like this:

json {   "method": "oidc",   "provider": "your-oidc-provider-id",   "csrf_token": "your-csrf-token",   "transient_payload": {     "custom_key": "custom_value",     "another_key": {       "nested": "data"     }   } }

The

transient_payload

must be a valid JSON object. This data will be passed along to any webhooks that are triggered during the authentication process, but it won't be permanently stored by Ory. This transient data can be particularly useful in OIDC flows when you need to pass additional context or parameters that should be available to your webhooks or email templates without being stored as part of the identity. For example, you might want to include information about the user's device, their preferences, or other contextual information that your application needs during the authentication process but doesn't need to store permanently. Remember that the transient payload is temporary and is primarily designed for passing data to webhooks and email templates during the flow execution.

I'll explain the complete API-only flow for OIDC login in Ory Identities. ## API-only OIDC Login Flow The API-only flow for OIDC login is designed for native applications (mobile apps, desktop apps, etc.) rather than browser-based applications. Here's the complete flow: ### 1. Initialize the Login Flow First, initialize the login flow using the API endpoint:

curl -s -X GET \     -H "Accept: application/json" \     https://$<http://PROJECT_SLUG.projects.oryapis.com/self-service/login/api|PROJECT_SLUG.projects.oryapis.com/self-service/login/api>

This returns a flow object with an ID and UI information:

json {   "id": "9d17f37b-b60b-44f5-9812-4829a89810f7",   "type": "api",   "expires_at": "2021-07-09T11:26:04.019418543Z",   "issued_at": "2021-07-09T10:26:04.019418543Z",   "request_url": "<http://playground.projects.oryapis.com/self-service/login/api>",   "ui": {     "action": "<https://playground.projects.oryapis.com/self-service/login?flow=9d17f37b-b60b-44f5-9812-4829a89810f7>",     "method": "POST",     "nodes": [ /* ... */ ]   } }

[Kratos Self-service Flows: Login for API Clients](https://www.ory.sh/docs/kratos/self-service/flows/user-login#login-for-api-clients-and-clients-without-browsers) ### 2. Submit the OIDC Login Request Next, submit a request to initiate the OIDC authentication:

curl -s -X POST \     -H "Accept: application/json" \     -H "Content-Type: application/json" \     -d '{"method": "oidc", "provider": "google", "csrf_token": "your-csrf-token"}' \     "https://$<http://PROJECT_SLUG.projects.oryapis.com/self-service/login?flow=<flow-id|PROJECT_SLUG.projects.oryapis.com/self-service/login?flow=<flow-id>>"

The response will include a redirect URL to the identity provider:

json {   "redirect_browser_to": "<https://accounts.google.com/o/oauth2/auth?client_id=...>" }

### 3. Handle the External Authentication For native apps, you need to: 1. Open the redirect URL in a system browser or embedded web view 2. Let the user authenticate with the identity provider 3. Capture the redirect back to your application via a custom URL scheme or other mechanism ### 4. Complete the Flow After the user authenticates with the identity provider and is redirected back, you need to: 1. Extract the necessary parameters from the redirect URL 2. Make a final request to complete the authentication

curl -s -X GET \     -H "Accept: application/json" \     "https://$<http://PROJECT_SLUG.projects.oryapis.com/self-service/login/flows?id=<flow-id|PROJECT_SLUG.projects.oryapis.com/self-service/login/flows?id=<flow-id>>"

### 5. Successful Authentication Upon successful authentication, Ory will respond with a session token instead of a cookie (since this is an API flow):

json {   "session_token": "oFZzgLpsacUpUy2cvQPtrGa2046WcXCR",   "session": {     "id": "8f660ce3-69ec-4aeb-9fda-f9230dc3243f",     "active": true,     "expires_at": "2020-08-25T13:42:15.7411522Z",     "authenticated_at": "2020-08-24T13:42:15.7411522Z",     "issued_at": "2020-08-24T13:42:15.7412042Z",     "identity": {       "id": "bf32596a-f853-47c4-91e6-a3f41cf4949d",       "schema_id": "default",       "schema_url": "<https://playground.projects.oryapis.com/schemas/default>",       "traits": {         "email": "<mailto:user@example.com|user@example.com>"       }       // ...     }   } }

[Kratos Self-service Flows: API clients](https://www.ory.sh/docs/kratos/self-service/flows/user-login#api-clients) ### 6. Using the Session Token You can use the session token for subsequent authenticated requests:

curl -s -H "Authorization: Bearer <session-token>" \   https://$<http://PROJECT_SLUG.projects.oryapis.com/sessions/whoami|PROJECT_SLUG.projects.oryapis.com/sessions/whoami>

## Important Notes 1. Never use API flows for browser applications as this opens security vulnerabilities 2. Native apps use the

/self-service/{flow-type}/api

endpoints instead of the browser endpoints 3. Ory issues a Session Token instead of a Session Cookie for API flows 4. You must include the session token in subsequent requests using the

Authorization

header This flow is specifically designed for native applications like mobile apps, desktop applications, and other non-browser clients.

I'll explain how to complete an API-based flow in Ory, specifically focusing on social sign-in for native applications. ## Completing an API-based Flow For native applications using social sign-in (like OIDC), completing the flow involves exchanging a session token exchange code for a session token after the user has authenticated with the identity provider. ### Session Token Exchange Process After the user authenticates with the identity provider and is redirected back to your application, you'll receive a code in the redirect URL. You then need to exchange this code for a session token: 1. Extract the

code

parameter from the redirect URL 2. Call the session token exchange endpoint

POST /self-service/methods/oidc/callback/:provider/exchange-session-token

The response will include a structure with a

continue_with

array that contains the session token:

json {   "continue_with": [     {       "action": "set_ory_session_token",       "ory_session_token": "your-session-token"     }   ] }

[Kratos API Reference](https://www.ory.sh/docs/kratos/reference/api) ### Native App Implementation For native apps, the flow completion involves these steps: 1. The user authenticates with the identity provider in a browser window 2. The browser redirects back to your app via a custom URL scheme (iOS Universal Link or Android App Link) 3. Your app extracts the code from the URL 4. Your app exchanges the code for a session token 5. Your app stores the session token securely for future authenticated requests As described in the [Social sign-in for native and mobile apps](https://www.ory.sh/docs/kratos/social-signin/native-apps) documentation, the flow looks like this:

// After receiving the redirect with the code parameter const code = getCodeFromUrl(redirectUrl);  // Exchange the code for a session token const response = await fetch(   `${ORY_SDK_URL}/self-service/methods/oidc/callback/${provider}/exchange-session-token`,   {     method: 'POST',     headers: {       'Content-Type': 'application/json',     },     body: JSON.stringify({ code }),   } );  const data = await response.json();  // Extract and store the session token const sessionToken = data.continue_with.find(   action => action.action === 'set_ory_session_token' ).ory_session_token;  // Store the session token securely await secureStorage.setItem('ory_session_token', sessionToken);

After completing the flow, you can use the session token for authenticated requests by including it in the Authorization header:

Authorization: Bearer <session-token>

This completes the API-based flow for social sign-in in native applications. Remember to configure your redirect URLs in the Ory Console under "Branding" → "Browser redirects" to allow the redirect back to your application.

Based on the error message you're receiving, it appears you're encountering an issue with the session token exchange process in Ory. The error "no session yet for this 'code'" typically occurs when the code you're trying to exchange is invalid, expired, or hasn't been properly generated yet. Here are some potential causes and solutions: 1. Incorrect or Expired Code: The session token exchange code might be expired or incorrect. These codes are typically short-lived. 2. Incomplete Flow: The authentication flow might not have completed successfully on the identity provider side before attempting to exchange the code. 3. Code Format Issues: You might be using the wrong format for the code or missing parts of it. For the session token exchange to work properly in native apps, you need both parts of the code: 1. The

init_code

- returned when initializing the flow with

return_session_token_exchange_code=true

2. The

return_to_code

- returned in the redirect URL after authentication When exchanging the session token, you need to call the

/sessions/token-exchange

endpoint with both parts:

GET /sessions/token-exchange?init_code=<init_code>&return_to_code=<return_to_code>

[Kratos API Reference](https://www.ory.sh/docs/kratos/reference/api) Make sure you're: - Initializing the flow with

return_session_token_exchange_code=true

- Correctly capturing both parts of the code - Making the exchange request before the code expires - Using the correct endpoint for the exchange If you're still encountering issues, check your application logs for more detailed error information and ensure you're following the complete flow as outlined in the [Social sign-in for native apps](https://www.ory.sh/docs/kratos/social-signin/native-apps#implementation) documentation.