Authentication Integration Guide

A comprehensive guide to integrating your application with the Eaglebirth Authentication Platform.

Prerequisites

Before starting the integration, you must configure your application on the Eaglebirth platform:

Create an App: Sign up at Eaglebirth.com and create a new project.
Get Credentials: Navigate to Dashboard > App. You will need your External ID for the frontend and your Client ID / Secret for the backend.

Base URL

https://auth.eaglebirth.com/

1. Generating PKCE Parameters

Eaglebirth uses PKCE (Proof Key for Code Exchange) to prevent authorization code interception attacks. You must generate a code_verifier (a random high-entropy string) and a code_challenge (SHA-256 hash of the verifier).

// 1. Generate Verifier (Random String)
function generateRandomString(length) {
  const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
  let result = '';
  const values = new Uint32Array(length);
  window.crypto.getRandomValues(values);
  for (let i = 0; i < length; i++) {
    result += charset[values[i] % charset.length];
  }
  return result;
}

// 2. Generate Challenge (SHA-256 hash of Verifier, Base64URL encoded)
async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await window.crypto.subtle.digest('SHA-256', data);
  
  return btoa(String.fromCharCode(...new Uint8Array(hash)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

// Usage
const verifier = generateRandomString(64);
const challenge = await generateCodeChallenge(verifier);

2. Initiating Authentication

To log a user in, redirect their browser to the root endpoint of the Eaglebirth platform using your external_id and the generated PKCE parameters.

javascript

// Example: Constructing the Login URL
const baseUrl = "https://auth.eaglebirth.com/";

// 1. Get parameters from previous step
const verifier = "GENERATED_VERIFIER";
const challenge = "GENERATED_CHALLENGE";

// 2. Generate Random State for CSRF protection
const state = generateRandomString(32);

// 3. Build Parameters
const params = new URLSearchParams({
  external_id: "YOUR_APP_EXTERNAL_ID",
  callback_uri: "https://your-app.com/callback", 
  state: state,
  code_challenge: challenge,
  code_challenge_method: "S256",
  template: "slimright" // Optional: Custom layout
});

// 4. Save verifier & state to local storage for later validation
sessionStorage.setItem('auth_verifier', verifier);
sessionStorage.setItem('auth_state', state);

// 5. Redirect User
window.location.href = `${baseUrl}?${params.toString()}`;

Query Parameters

Parameter	Required	Type	Description
external_id	Yes	string	Your unique Application ID provided by Eaglebirth.
callback_uri	Yes	URL	Where the user is redirected after login. Must match the allowed URI in your app settings.
state	Optional	string	Random string to prevent CSRF. Returned unchanged in the callback. (Strongly recommended)
code_challenge	Optional	string	Base64URL encoded SHA-256 hash of the code verifier (PKCE). (Strongly recommended)
code_challenge_method	Optional	string	Defaults to "S256". Can be set to "S256" or "plain". (Strongly recommended)
template	Optional	string	UI Layout options: "slimleft" or "slimright". Defaults to centered card.

3. UI Customization

You can control the visual layout of the login page using the template parameter. The platform also automatically respects the user's system preferences for Light/Dark mode.

Default

(None)

Centered card layout. Best for simple, focused login flows.

Slim Left

slimleft

Split screen. Login form on the left, Brand image on the right.

Slim Right

slimright

Split screen. Brand image on the left, Login form on the right.

Note: The background image used in Slim layouts is configured in your App Dashboard settings (Background Image URL). If not set, a default abstract image is used.

4. Available Features

The platform automatically handles complex authentication scenarios based on your application's security requirements.

Standard Login: Username/Email/Phone & Password.
Magic Links: Users can request a secure login link via email (PKCE & State are preserved).
Social Login: Native support for Google, GitHub, Apple, Yahoo, etc.
MFA (Verification): If enabled, users are challenged via SMS, Email OTP, or WhatsApp.
Identity Verification (KYC): If enabled, users must upload an ID Card and pass a Face Liveness check before accessing your app.

5. Handling the Callback

Upon success, the user is redirected back to your callback_uri with the authorization code and state.

text

https://your-app.com/callback?code=AUTH_CODE_HERE&state=YOUR_STATE_HERE

Integration Steps

⚠️ Authentication Required

The code exchange endpoint is protected. Your backend must first authenticate with Eaglebirth using your Client ID and Secret to obtain an Access Token.

View App Authentication Docs

Validate State: Check that the state query parameter matches the one you stored in local storage in Step 1.
Get Access Token: Authenticate your backend with Eaglebirth to get a Bearer Token (see the warning box above).
Exchange Code: Send a POST request to the Eaglebirth backend with the Bearer Token and the code + code_verifier to get the user session.

const fetch = require('node-fetch');

const response = await fetch('https://eaglebirth.com/api/app/users/sign_app_user_in/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN' // Obtained via App Authentication
  },
  body: JSON.stringify({
    code: "AUTH_CODE_FROM_URL",
    code_verifier: "YOUR_STORED_VERIFIER" 
  })
});

const userSession = await response.json();
console.log(userSession);

View Full API Reference