Login Flow APIs Overview

Get an overview of the Pangea authentication APIs

AuthN login flow APIs (AuthN APIs) serve as the foundation for Pangea authentication solutions, such as AuthN Hosted Login. Using these APIs, you can build completely custom login functionality directly into your application, so your users never leave it during authentication.

To use AuthN APIs, you need to sign up for a free Pangea account and enable and configure the AuthN service in your Pangea project.

In your application, you need to build the authentication UI and the functionality for processing user responses by making calls to the AuthN APIs.

note

You can use Pangea SDKs to streamline interactions with the AuthN APIs.

After users are authenticated, your application will receive an active token and a refresh token containing Pangea user session and profile information. This information can be used to create new user records or link to existing ones and to populate user sessions in your application. To keep the local user session synchronized with the user session at Pangea, you can use the /v2/client/token/check, /v2/client/session/refresh, and /v2/session/logout endpoints in the AuthN APIs.

Limitations

When you use the AuthN login flow APIs directly, you cannot reuse authenticators built by Pangea for interacting with users in their browsers. You will have to build your functionality for:

• Captcha
• Social authenticators
• Passkeys

In addition, you will need to provide the user's IP for threat intelligence security controls in the context of your requests to the AuthN APIs.

Authentication phases

AuthN login flows are built around the concepts of phases and Log in/Sign up flow authentication steps within each phase.

1. Primary Phase - Determines if a user exists and initiates either a sign-up or sign-in process. This phase also includes email address validation and options for password reset.
2. Secondary Phase - Provides options for secondary authentication methods, like one-time password (OTP) via email or SMS, or time-based one-time password (TOTP) via an authenticator app. The secondary phase can be repeated with different authentication methods.
3. Completed Phase - Marks the end of the mandatory steps in the flow and results in the user session at Pangea. Your application receives the session tokens and user profile.

Until the flow is completed, AuthN maintains an authentication state, which is updated with every request to the AuthN flow APIs.

API endpoints

The following endpoints are used to initiate and manage authentication flows:

• /v2/flow/start - Begins a standard authentication flow for signing up or signing in users.

  Requires a cb_uri parameter populated with a pre-registered in Redirect (Callback) Settings URI.

  Returns the new flow state, including flow_id and the available flow_choices with which you can continue the authentication.

• /v2/flow/update - Updates the flow with the selected authentication method, such as password or a single-use code.

  Requires the flow_id parameter as a reference to the started flow, the authenticator choice, and any additional data required for the authenticator.

  Returns the current flow state, including flow_id, and any additional authenticator choices.

• /v2/flow/restart - Starts or restarts an authenticator. For example, before you can use an OTP authenticator, it needs to be "restarted" and send a message to the user.

  Requires the flow_id parameter as a reference to the started flow and an authenticator choice.

  Returns the current flow state, including flow_id, the information about the executed authenticator, and any additional authenticator choices.

• /v2/flow/complete - Completes the flow and discards its state.

  Requires a flow_id parameter as a reference to the flow to complete.

  Returns the user profile and session tokens.

All requests to AuthN APIs have to be authorized with an AuthN service token:

Authorization: Bearer <Pangea-AuthN-token>

Follow the links to the endpoints' documentation in the interactive API reference to learn more about their parameters and responses.

Overall flow

Below, find a generalized login flow built with AuthN APIs. You can combine different authentication methods to build custom sign-up and sign-in functionality. The next chapters provide detailed examples for both login scenarios, which you can modify and adjust to your needs.

Diagram

Annotations

1. A signed-out user clicks a login link or tries to access a restricted area in your application.
2. Your application starts the authentication flow by making a call to AuthN APIs.
3. 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.
4. Your application prompts the user to provide their username.
5. The user provides their username.
6. Your application submits the username to AuthN.
7. AuthN responds with pre-configured Log in/Sign up flow authentication choices.
8. Your application prompts the user to make a selection and provide any necessary input, such as the user's credentials or email.
9. The user chooses an authentication method and provides any necessary input.
10. Your application submits the user's input to AuthN.
11. AuthN responds with the phase completed status when all authentication requirements are met.
12. Your application makes a final call to the AuthN APIs and completes the sign-in process.
13. AuthN responds with an active user token for session validation and a refresh token for renewing the expired active token.
14. Your application uses the user data received from Pangea to create a local user (if necessary) and populate the local user session.
    • If the active token value is opaque, your application uses the /v2/client/token/check endpoint to verify the user's session and get their profile.
    • If the active token value is a signed JWT, the validated and decoded token can serve as the session confirmation and the source of user profile data.