Complete Sign-up flow (user is not found)
Complete user sign-up and sign-in in your application and request user profile and session tokens from AuthN
The authentication flow below describes an example sign-up process for users who selected the password option as their primary authentication method. Email Verification is enabled in AuthN Signup Settings in the Pangea User Console.
Diagram
Example authentication flow with password as the primary authentication method and email verification enabled
Annotations
-
AuthN responds with pre-configured Log in/Sign up flow primary authentication choices.
Return authentication choices (1)
/v2/flow/update responsejson{ "status": "Success", "summary": "Flow updated", "result": { "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi", "flow_type": [ "signup" ], "username_format": "string", "username": "example", "flow_phase": "phase_primary", "flow_choices": [ { "choice": "password", "data": { "enrollment": true, "password_policy": { "chars_min": 8, "chars_max": 64, "lower_min": 1, "upper_min": 1, "punct_min": 1, "number_min": 1 }, "need_email": true } }, { "choice": "email_otp", "data": { "sent": false, "enrollment": true, "resend_time": "0001-01-01T00:00:00Z", "need_email": true } }, { "choice": "magiclink", "data": { "sent": false, "resend_time": "0001-01-01T00:00:00Z", "state": "pcb_6wof6jdhncd336cjvfptvjoxuze5aiv5", "need_email": true } }, { "choice": "sms_otp", "data": { "sent": false, "enrollment": true, "resend_time": "0001-01-01T00:00:00Z", "need_phone": true } }, { "choice": "totp", "data": { "enrollment": true, "totp_secret": { "qr_image": "data:image/png;base64,iVBORw...SuQmCC", "secret": "WAXBVK...RRI3Y4" } } } ] } }, ...Note that the
result.flow_typeis "signup" and the "need_email" and "need_phone" fields indicate that additional input is required. When the user selects an authentication method, your application must request any additional data, such as email or phone, that is required for this authentication method. -
Your application prompts the user to make a selection and provide any necessary input, such as the user's credentials or email.
-
The user chooses an authentication method and provides any necessary input.
-
Your application submits the user's password and required email to AuthN.
Submit user password and email (4)
Parameters:
-
"flow_id" - The
result.flow_idvalue returned in the initial and previous AuthN responses -
"choice" - The authenticator
choiceout of theresult.flow_choicesreturned in the previous AuthN response -
"data" - The user input required for the selected authenticator
POST/v2/flow/updatecURLcurl --location "https://authn.$PANGEA_DOMAIN/v2/flow/update" \ --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \ --header 'Content-Type: application/json' \ --data-raw '{ "flow_id": "'"$FLOW_ID"'", "choice": "password", "data": { "password": "AzdJ5#3p", "email": "example.user@example.com" } }' -
-
AuthN validates input and responds with the profile fields to be populated, such as first and last names.
Return profile fields choice (5)
/v2/flow/update responsejson{ "status": "Success", "summary": "Flow updated", "result": { "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi", "flow_type": [ "signup" ], "username_format": "string", "username": "example", "flow_phase": "phase_profile", "flow_choices": [ { "choice": "profile", "data": { "fields": [ { "id": "first_name", "label": "First Name", "type": "string", "show_on_signup": true, "required": true, "builtin": true, "display_disabled": false }, { "id": "last_name", "label": "Last Name", "type": "string", "show_on_signup": true, "required": true, "builtin": true, "display_disabled": false }, { "id": "phone", "label": "Phone", "type": "string", "show_on_signup": false, "required": false, "builtin": true, "display_disabled": false } ] } } ] } }, ... -
Your application prompts the user for profile information.
-
The user provides profile information.
-
Your application submits the user's input to AuthN.
Submit profile information (8)
Parameters:
-
"flow_id" - The
result.flow_idvalue returned in the initial and previous AuthN responses -
"choice" - The profile "choice" required for user enrollment and returned in the previous AuthN response
-
"data" - The user input required for a new user record
POST/v2/flow/updatecURLcurl --location "https://authn.$PANGEA_DOMAIN/v2/flow/update" \ --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "flow_id": "'"$FLOW_ID"'", "choice": "profile", "data": { "profile": { "first_name": "Example", "last_name": "User" } } }' -
-
AuthN responds with the email verification choice (if email verification is enabled, but has not been done during the sign-up process in the email OTP flow)
Return email verification choice (9)
/v2/flow/update responsejson{ "status": "Success", "summary": "Flow updated", "result": { "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi", "flow_type": [ "signup" ], "username_format": "string", "username": "example", "flow_phase": "phase_verify_email", "flow_choices": [ { "choice": "verify_email", "data": { "sent": false, "resend_time": "0001-01-01T00:00:00Z", "state": "pcb_yxae67fvyzdsqvrvbu3floy33prde3nw" } } ] } }, ... -
Your application requests AuthN to send the user an email with a verification link.
Request email verification (10)
Parameters:
-
"flow_id" - The
result.flow_idvalue returned in the initial and previous AuthN responses -
"choice" - The required email verification
choicereturned in the previous AuthN response -
"data" - An empty object required for a flow restart
POST/v2/flow/restartcURLcurl --location "https://authn.$PANGEA_DOMAIN/v2/flow/restart" \ --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "flow_id": "'"$FLOW_ID"'", "choice": "verify_email", "data": {} }'Your application may inform the user that they are expected to verify their email before they can sign in.
-
-
AuthN sends the user an email with a verification link.
-
AuthN responds with a confirmation that the email verification link has been sent.
Confirm email verification link sent (12)
/v2/flow/restart responsejson{ "status": "Success", "summary": "Flow updated", "result": { "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi", "flow_type": [ "signup" ], "username_format": "string", "username": "example", "flow_phase": "phase_verify_email", "flow_choices": [ { "choice": "verify_email", "data": { "sent": true, "resend_time": "2024-06-16T03:34:27.901732278Z", "state": "pcb_vrf6n6asalthfpqccy5v3nbvl7zxnofd" } } ] } }, ... -
The user follows the link and clicks the Verify button on the Pangea-hosted page. If enabled, email verification needs to be done before the user's first login.
-
The Pangea server redirects the user to the application's redirect route including the
flow_idand thestatein the URI query. -
The user's browser redirects to the application with the
flow_idand thestatein the URI query.Redirect to App (14)
http://localhost:5173/redirect?flow=pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi&state=pcb_vrf6n6asalthfpqccy5v3nbvl7zxnofdNote that your application can check if the
flow_idandstatevalues in the redirect URL query match the ones in the AuthN response to the request for a verification email. If the values match, the redirect is the result of the user following the verification link and your application can proceed with the user authentication. -
Your application checks if email has been verified, and does not proceed until it is done.
Check if email verified (16)
Parameters:
-
"flow_id" - The
result.flow_idvalue returned in the initial and previous AuthN responses -
"choice" - An empty string, because no additional input is required for the email verification performed by the user
-
"data" - An empty object, because no input is required
POST/v2/flow/updatecURLcurl --location "https://authn.$PANGEA_DOMAIN/v2/flow/update" \ --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "flow_id": "'"$FLOW_ID"'", "choice": "", "data": {} }' -
-
AuthN responds with the secondary authentication choices pre-configured in Log in/Sign up flow settings if multi-factor authentication (MFA) is enabled.
Return secondary MFA choices (17)
/v2/flow/update responsejson{ "status": "Success", "summary": "Flow updated", "result": { "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi", "flow_type": [ "signup" ], "username_format": "string", "username": "example", "flow_phase": "phase_secondary", "flow_choices": [ { "choice": "email_otp", "data": { "sent": false, "enrollment": true, "resend_time": "0001-01-01T00:00:00Z", "can_update_email": true } }, { "choice": "magiclink", "data": { "sent": false, "resend_time": "0001-01-01T00:00:00Z", "state": "pcb_dil7mdqnjxzqwl2aonrqjxfuonmlccew", "can_update_email": true } }, { "choice": "sms_otp", "data": { "sent": false, "enrollment": true, "resend_time": "0001-01-01T00:00:00Z", "need_phone": true } }, { "choice": "totp", "data": { "enrollment": true, "totp_secret": { "qr_image": "data:image/png;base64,iVBORw...5CYII=", "secret": "PVKNHE...U5XD2J" } } } ] } }, ... -
Your application prompts the user to select an MFA method.
-
The user selects an MFA method.
-
Your application submits the user's MFA selection to AuthN.
Submit MFA choice (20)
Parameters:
-
"flow_id" - The
result.flow_idvalue returned in the initial and previous AuthN responses -
"choice" - The MFA authenticator
choiceout of theresult.flow_choicesreturned in the previous AuthN response -
"data" - An empty object required for a flow restart
POST/v2/flow/restartcURLcurl --location "https://authn.$PANGEA_DOMAIN/v2/flow/restart" \ --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "flow_id": "'"$FLOW_ID"'", "choice": "email_otp", "data": {} }' -
-
AuthN sends the user an OTP and responds with the confirmation of which MFA method is being used.
Confirm MFA executed (21)
/v2/flow/restart responsejson{ "status": "Success", "summary": "Flow updated", "result": { "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi", "flow_type": [ "signup" ], "username_format": "string", "username": "example", "flow_phase": "phase_secondary", "flow_choices": [ { "choice": "email_otp", "data": { "sent": true, "enrollment": true, "resend_time": "2024-06-12T21:19:33.504896793Z", "can_update_email": true } }, ... ] } }, ... -
Your application prompts the user for the temporary credential.
-
The user provides the temporary credential.
-
Your application submits the user's input to AuthN.
Submit OTP (24)
Parameters:
-
"flow_id" - The
result.flow_idvalue returned in the initial and previous AuthN responses -
"choice" - The executed (sent) MFA authenticator
choicereturned in the previous AuthN response -
"data" - The user input required for the selected authenticator
POST/v2/flow/updatecURLcurl --location "https://authn.$PANGEA_DOMAIN/v2/flow/update" \ --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "flow_id": "'"$FLOW_ID"'", "choice": "email_otp", "data": { "code": "198952" } }' -
-
AuthN responds with a phase completed message and includes possible additional MFA choices that your application can optionally perform.
Return Phase completed and remaining MFA choices (25)
/v2/flow/update responsejson{ "status": "Success", "summary": "Flow updated", "result": { "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi", "flow_type": [ "signup" ], "username_format": "string", "username": "example", "flow_phase": "phase_completed", "flow_choices": [ { "choice": "sms_otp", "data": { "sent": false, "enrollment": true, "resend_time": "0001-01-01T00:00:00Z", "need_phone": true } }, { "choice": "totp", "data": { "enrollment": true, "totp_secret": { "qr_image": "data:image/png;base64,iVBORw...SuQmCC", "secret": "ZHXHMV...OGMODS" } } } ] }, ... } -
Your application makes a final call to the AuthN APIs and completes the sign-in process.
Complete the flow (26)
Parameters:
- "flow_id" - The
result.flow_idvalue returned in the initial and previous AuthN responses
POST/v2/flow/completecURLcurl --location "https://authn.$PANGEA_DOMAIN/v2/flow/complete" \ --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "flow_id": "'"$FLOW_ID"'" }' - "flow_id" - The
-
AuthN responds with the user profile information, an active user token for session validation, and a refresh token for renewing the expired active token.
Return user profile and session tokens (27)
In the authentication response, you will receive the user profile information and the session tokens. The format of the user active token will depend on the AuthN Session Configuration settings in the Pangea User Console:
-
Opaque Session Tokens - The active token value is a unique identifier that references a session managed by Pangea. Your application uses the /v2/client/token/check endpoint to verify the user's session and get their profile.
-
JSON Web Tokens (JWT) - The active token is a standard, optionally signed JWT with encoded user and claims information. The validated and decoded token can serve as the session confirmation and the source of user profile data.
authentication responseopaque session tokens response{ "status": "Success", "result": { "active_token": { "token": "ptu_kuoqvvxk4yhirapuhw6bs7nunp", "id": "pmt_e3nqvvxk4yhirapuhw6bs7n7sk", "type": "user", "life": 172799, "expire": "2024-05-12T21:16:19.029336Z", "enabled": true, "identity": "pui_cgwqvvxk4yhirapuhw6bs7nbxr", "email": "example.user@example.com", "owner": "example.user@example.com", "profile": { "email": "example.user@example.com", "first_name": "Example", "last_name": "User", "phone": "907...", ... }, "created_at": "2024-05-10T21:16:19.037372Z", "intelligence": { "embargo": false, "ip_intel": { "is_bad": false, "reputation": { ... }, "geolocation": { ... }, "is_vpn": false, "is_proxy": true }, "domain_intel": { "is_bad": false, "reputation": { ... } }, "user_intel": false } }, "refresh_token": { "token": "ptr_tukqvvxk4yhirapuhw6bs7nj3k", "id": "pmt_7agqvvxk4yhirapuhw6bs7npay", "type": "session", "life": 172799, "expire": "2024-05-12T21:16:19.029336Z", "enabled": true, "identity": "pui_cgwqvvxk4yhirapuhw6bs7nbxr", "email": "example.user@example.com", "owner": "example.user@example.com", "profile": { "email": "example.user@example.com", "first_name": "Example", "last_name": "User", "phone": "907...", ... }, "created_at": "2024-05-10T21:16:19.030784Z", "intelligence": { "embargo": false, "ip_intel": { "is_bad": false, "reputation": { ... }, "geolocation": { ... }, "is_vpn": false, "is_proxy": true }, "domain_intel": { "is_bad": false, "reputation": { ... } }, "user_intel": false } } }, ... } -
Was this article helpful?