Loading ...
Loading ...
A comprehensive guide to integrating your application with the Eaglebirth Authentication Platform.
Before starting the integration, you must configure your application on the Eaglebirth platform:
https://auth.eaglebirth.com/
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);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.
// 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()}`;| 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. |
You can control the visual layout of the login page using the template parameter. The platform offers 9 professional layout templates to match any brand identity. All layouts automatically support Light/Dark mode based on user system preferences.
(default)Classic centered card layout. Professional, familiar, and works for any use case.
template=slimleftSplit screen with form on left and brand image on right. Professional SaaS look.
template=slimrightSplit screen with brand image on left and form on right. Visual-first approach.
template=glassModern glassmorphism with blurred backdrop and animated gradient. Perfect for premium brands.
template=minimalUltra-clean, distraction-free design. Ideal for enterprise and professional applications.
template=gradientVibrant animated multi-color gradient background. Great for creative, energetic brands.
template=splitcenterUnique split background panels with centered form. Luxury, high-end aesthetic.
template=sidebarFull-height marketing sidebar with features showcase. Perfect for SaaS products.
template=cardstack3D layered cards with depth effect. Modern, eye-catching, and memorable.
Enterprise/Professional: Use minimal, auth, or sidebar
Tech/Startup: Use glass, gradient, or cardstack
Luxury/Premium: Use splitcenter, cardstack, or glass
SaaS/B2B: Use sidebar, slimleft, or minimal
Creative/Agency: Use gradient, cardstack, or slimright
Note: Background images (used in layouts like Slim, Split Center, Glass, and Card Stack) are configured in your App Dashboard settings. If not set, default images or gradients are used. The Sidebar layout also supports custom app name and tagline from your dashboard settings.
The platform automatically handles complex authentication scenarios based on your application's security requirements.
Upon success, the user is redirected back to your callback_uri with the authorization code and state.
https://your-app.com/callback?code=AUTH_CODE_HERE&state=YOUR_STATE_HEREThe code exchange endpoint is protected. Your backend must use an API Key in the Authorization header for all API requests.
Manage API Keysstate query parameter matches the one you stored in local storage in Step 1.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_EAGLEBIRTH_API_KEY' // Get this from /dashboard/app/api-keys
},
body: JSON.stringify({
code: "AUTH_CODE_FROM_URL",
code_verifier: "YOUR_STORED_VERIFIER"
})
});
const userSession = await response.json();
console.log(userSession);