Skip to main content

Get Authorization Code Flow Login UI

GET 
/auth/brands/:brandIdentity/login

Overview​

The Login API is an internal endpoint hosted on a dedicated authentication domain. It supports the OAuth 2.0 Authorization Code flow by rendering the login UI. This API is directly invoked via the /authorize endpoint, which is partner-facing. The /authorize endpoint redirects clients to the /login endpoint on the authentication domain, ensuring a seamless and secure user authentication experience.

How Authorization Code Flow works​

  1. User initiates a Login process through the Paysafe Embedded Wallet SDK.

  2. Paysafe Embedded Wallet SDK redirects user to login page (/authorize endpoint).

  3. User authenticates using one of the configured login options.

  4. Upon successful authentication, the authorization endpoint redirects the user back to the application with a single-use authorization code.

  5. The application exchanges the authorization code with the Paysafe Embedded Wallet’s Token endpoint, sending along the client credentials and PKCE verifier.

  6. The token endpoint verifies the authorization code, client credentials, and PKCE verifier.

  7. The token endpoint responds with an access token (optionally refresh token and ID token).

  8. The application uses the access token to call the wallet’s APIs to access user information or perform actions.

  9. The wallet API responds with the requested data or performs the requested operation.

Purpose​

The Login API is designed to:

  • Render the Login UI: Serve the HTML content for the login page on the authentication domain.
  • Handle Authentication Outcomes: Manage success and error scenarios, either redirecting users to the provided redirect_uri or a custom failure page.
  • Enhance Security: Host the login UI on a separate domain to isolate authentication operations.

Workflow​

  1. Initiation via /authorize:

    • A client initiates a request to the /authorize endpoint.
    • The /authorize endpoint redirects the user (HTTP 302) to the /login endpoint on the authentication domain.

  2. Processing by /login:

    • Success:
      • The /login endpoint serves a 200 OK response with the HTML content of the login page.
      • The /login endpoint returns a 302 FOUND response and redirects the user to an external HTML-based login page.
    • Error:
      • If the provided redirect_uri is invalid, the /login endpoint redirects to a custom failure page.
      • If the redirect_uri is valid, the /login endpoint redirects back to the redirect_uri with error and error_description query parameters, as described by RFC 6749 §4.1.2.1.

  3. User Authentication:

    • Users interact with the login UI to authenticate.
    • On successful authentication, the user is redirected to the redirect_uri with code as a query parameter.

Security Considerations​

  • Domain Isolation: Hosting the login UI on a separate domain (auth.paysafe.com) ensures stricter security controls for authentication processes.
  • Strict Redirect URI Validation: Only valid redirect_uri values are used for redirections to prevent open redirect vulnerabilities.
  • OAuth 2.0 Compliance: The Login API strictly adheres to the OAuth 2.0 specification for error reporting and redirection behavior.

Intended audience​

This endpoint is implicitly triggered as part of the OAuth 2.0 Authorization Code flow. It facilitates the secure execution of the login process, enabling the rendering of the login UI and managing user authentication. This endpoint is NOT intended to be directly invoked by partners, but serves as a critical step within the overall authentication flow.

Request​

Responses​

This endpoint initiates the OAuth 2.0 authorization process by displaying an authentication page to the end-user’s browser. Once the user completes the authentication and authorization steps, the endpoint redirects to the client’s specified redirection endpoint with the appropriate parameters. #### Success Behavior Returns the actual HTML content shown to a user agent to begin the OAuth 2 authorization process. If the `client_id` and `redirect_uri` match the client configuration on the authorization server, and the user has entered valid credentials, they are redirected to the specified redirection endpoint as defined by [RFC 6749 §4.1.2] with the following query parameters: - `code`: The authorization code, to be exchanged for an access token. - `state`: A value originally sent by the client to maintain request integrity and prevent CSRF attacks. [RFC 6749 §4.1.2]: https://tools.ietf.org/html/rfc6749#section-4.1.2