SSO

Single Sign-On (SSO) allows you to integrate Aella authentication into your application. This enables your users to sign in to your application using their Aella credentials.

Why make users create yet another account? With Aella SSO, your users can sign in using their existing Aella credentials. It's like "Sign in with Google" but for Aella—seamless, secure, and user-friendly. Perfect for apps that want to leverage Aella's user base or provide a unified experience across Aella services.

Client App

Create

This endpoint is used to register a new Single Sign-On (SSO) client application on the Aella SSO platform.

Register your app for SSO

Before you can use Aella SSO, you need to register your application. This creates a client app with your branding, redirect URIs, and security settings. Once registered, you'll get a client key that you'll use for authentication flows.

Common use cases

Partner integrations: Integrate Aella authentication into partner applications or services.
Internal tools: Allow Aella employees to sign in to internal tools using their Aella credentials.
Third-party services: Enable Aella users to access third-party services with their existing accounts.
White-label solutions: Provide SSO capabilities to clients who want to integrate with Aella.
Mobile apps: Register mobile applications that need Aella authentication.
Web portals: Set up web portals that require Aella user authentication.

What you'll need

App details: Name, description, logo, and branding information.
Security settings: Authorized redirect URIs and CORS origins for your app.
Legal pages: Privacy policy and terms of service URLs.
Contact information: Support and contact emails.

Request Body

Name
name
Type
string
Description
Name of the client application.
Name
logo_url
Type
string
Description
URL of the logo to display for the app.
Name
description
Type
string
Description
Short description of the client app.
Name
support_email
Type
string
Description
Email address for support requests.
Name
authorized_redirect_uris
Type
array
Description
List of redirect URIs for OAuth callback.
Name
authorized_origins
Type
array
Description
List of allowed CORS origins.
Name
homepage_url
Type
string
Description
The public homepage of the client application.
Name
privacy_policy_url
Type
string
Description
Link to the app's privacy policy.
Name
terms_of_service_url
Type
string
Description
Link to the app's terms and conditions.
Name
contact_email
Type
string
Description
Email address to be shown on the client profile or for direct contact from the Aella team for updates.

Request

POST

/sso-client-app

curl https://api.aellaapp.com/sso-client-app \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aella Internal Demo",
    "logo_url": "https://storage.googleapis.com/sso-frontend-media/logos/juve.png",
    "description": "This client app is for aella Demo.",
    "support_email": "support@aellacredit.com",
    "authorized_redirect_uris": [
      "https://example.com/auth/callback"
    ],
    "authorized_origins": [
      "https://example.com/"
    ],
    "homepage_url": "https://aellaapp.com/",
    "privacy_policy_url": "https://aellaapp.com/privacy-policy",
    "terms_of_service_url": "http://aellaapp.com/terms-and-conditions",
    "contact_email": "info@aellamfb.com"
  }'

Response

{
  "status": "success",
  "title": "New Single Sign On App",
  "data": {
    "name": "Aella Internal Demo",
    "description": "This client app is for aella Demo.",
    "logo_url": "https://storage.googleapis.com/sso-frontend-media/logos/juve.png",
    "client_key": "public.aellasso.aaba9f0f711fe6f4dc7947b316b79c",
    "authorized_redirect_uris": [
      "https://example.com/auth/callback"
    ],
    "authorized_origins": [
      "https://example.com/"
    ],
    "homepage_url": "https://aellaapp.com/",
    "privacy_policy_url": "https://aellaapp.com/privacy-policy",
    "terms_of_service_url": "http://aellaapp.com/terms-and-conditions",
    "contact_email": "info@aellamfb.com",
    "support_email": "support@aellacredit.com",
    "is_active": true,
    "environment": "LIVE",
    "deleted_at": null,
    "id": "18473b14-c5e7-404d-8dc6-df71123483e4",
    "created_at": "2025-05-13T15:00:18.158Z",
    "updated_at": "2025-05-13T15:00:18.158Z"
  }
}

Auth Flow

Get Auth URL

This endpoint generates an authorization URL for the SSO authentication flow. The user will be redirected to this URL to authenticate.

Start the authentication flow

This endpoint generates the URL where users will sign in with their Aella credentials. Redirect your users to this URL, and after they authenticate, they'll be sent back to your app with an authorization code or token.

Common use cases

Login button: When users click "Sign in with Aella" in your app, generate the auth URL and redirect them.
OAuth flow: Implement the standard OAuth 2.0 authorization flow for Aella SSO.
Mobile app authentication: Generate auth URLs for mobile apps that need Aella authentication.
Web app integration: Set up SSO for web applications that want to use Aella authentication.

How it works

Generate URL: Call this endpoint to get the authorization URL.
Redirect user: Send the user to the generated URL.
User authenticates: User signs in with their Aella credentials on Aella's login page.
Callback: User is redirected back to your app with an authorization code or token.
Exchange token: Use the code/token to get user information via the Get User endpoint.

Request Body

Name
client_key
Type
string
Description
The client key obtained from creating a client app.
Name
redirect_uri
Type
string
Description
The redirect URI where the user will be sent after authentication. Must match one of the authorized redirect URIs.

Request

POST

/sso/authorize/auth-url

curl https://api.aellaapp.com/sso/authorize/auth-url \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "client_key": "public.aellasso.aaba9f0f711fe6f4dc7947b316b79c",
    "redirect_uri": "https://example.com/auth/callback"
  }'

Response

{
  "status": "success",
  "title": "Auth URL generated successfully",
  "data": {
    "auth_url": "https://sso.aella.app/authorize?client_key=public.aellasso.aaba9f0f711fe6f4dc7947b316b79c&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fcallback&state=adcdd686cde3ec6e5dbc505b87308480",
    "state": "adcdd686cde3ec6e5dbc505b87308480"
  }
}

User

Get User

This endpoint retrieves the authenticated user's information. Requires an SSO token in the header.

Get authenticated user details

After a user successfully authenticates via SSO, use this endpoint to retrieve their profile information. You'll get their name, email, phone number, and other details—everything you need to create or update their account in your system.

Common use cases

User profile creation: Create user accounts in your system using Aella user data.
Account linking: Link existing accounts to Aella user identities.
Profile display: Show authenticated user information in your app's user profile section.
Personalization: Use user data to personalize the experience in your application.
Authorization: Check user details to determine what features or data they can access.
Session management: Verify user identity and maintain authenticated sessions.

What you'll get

User ID, email, first name, last name
Phone number
Other profile information (depending on what Aella provides)

Headers

Name
sso-token
Type
string
Description
The SSO token obtained from the authentication callback.

Request

GET

/sso/users/me

curl https://api.aellaapp.com/sso/users/me \
  -H "sso-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

{
  "status": "success",
  "data": {
    "id": "52430dfb-1151-4c6d-9839-f5ceff82c5f6",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+2349012345678"
  }
}