Start Authentication Flow

Start authentication implemented with AuthN login flow APIs

Diagram

Annotations

1. A signed-out user clicks a login link or tries to access a restricted area in your application.

2. Your application checks if the user's request is authorized with a session cookie or a valid token in the Authorization header.

3. Your application starts the authentication flow by making a call to AuthN APIs.

   Start login flow (3)

   Parameters:

   • "cb_uri" - The application redirect route URI pre-registered in Redirect (Callback) Settings
   POST/v2/flow/start

   cURL

   Code Snippet Language

   curl --location "https://authn.$PANGEA_DOMAIN/v2/flow/start" \
   --header "Authorization: Bearer $PANGEA_AUTHN_TOKEN" \
   --header 'Content-Type: application/json' \
   --data '{
       "cb_uri": "http://localhost:5173/redirect"
   }'
   

4. AuthN creates an authentication flow state for the current authentication attempt and requests the username. On every consequent request to AuthN APIs, the authentication state is updated.

   Return username choice (4)

   /v2/flow/start response

   json

   Code Snippet Language

   {
     "status": "Success",
     "summary": "Flow started",
     "result": {
       "flow_id": "pfl_od5zv3nsvgmngk5evkwhp32eakmaj2fi",
       "flow_type": [
         "signup",
         "signin"
       ],
       "username_format": "string",
       "flow_phase": "phase_primary",
       "flow_choices": [
         {
           "choice": "set_username",
           "data": {
             "required_for": [
               "password",
               "email_otp",
               "magiclink",
               "sms_otp",
               "totp"
             ]
           }
         }
       ]
     },
     ...
   }
   

   The result.flow_id value in the response is a reference to the current authentication state, which persists during the login process. Your application must use it in all consequent requests to the AuthN login flow APIs to complete the authentication.

   export FLOW_ID=<result.flow_id>

5. Your application prompts the user to provide their username.

6. The user provides their username.

7. Your application submits the username to AuthN.

   Submit username (7)

   Parameters:

   • "flow_id" - The result.flow_id value returned in the initial and the initial AuthN response

   • "choice" - The username choice returned in the initial AuthN response

   • "data" - The user input required for the username "choice"

   POST/v2/flow/update

   cURL

   Code Snippet Language

   curl --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": "set_username",
       "data": {
           "username": "example"
       }
   }'
   

   The response from AuthN will vary depending on whether the user is found and what Log in/Sign up flow primary authentication choices are pre-configured in the Pangea User Console .