Developer Integration Guide

Developer Brief

UmmahPass OAuth is standard OAuth 2.0. It works with any language, framework, or platform. If your stack supports OAuth (and they all do), you can integrate UmmahPass. Your users log in once and get access to all Ummah ecosystem sites. You get verified user data back, no need to build your own auth.

What you need

Client ID (we give you this)
Client Secret (we give you this)
Redirect URI (you tell us yours)

Email salaam@ummahpass.io to get your credentials.

What you get back

id: Unique UmmahPass user ID
name, email: User identity
is_pro, is_verified_muslim: Membership + verification
points_balance, points_multiplier: Points economy

3 URLs to configure

Authorize: https://ummahpass.io/oauth/authorize

Token: https://ummahpass.io/oauth/token

User Info: https://ummahpass.io/api/user

1. Quick Start Checklist

Follow these 6 steps in order. Most developers complete integration in under an hour.

Get Your OAuth Credentials

You need 3 things from us to get started. Email salaam@ummahpass.io with your website URL and desired callback URL, and we'll send you:

Client ID: identifies your app
Client Secret: authenticates your server (keep this private)
Redirect URI: your callback URL, registered on our end

That's it. No SDK to install, no library required. These 3 values + the 3 URLs in the brief above are everything you need, regardless of your tech stack.

Set Up Your Redirect URI

Create a callback endpoint on your site that will receive the authorization code. This URL must exactly match what you gave us in Step 1.

Example: https://yoursite.com/auth/ummahpass/callback

Add a "Login with UmmahPass" Button

Add a button on your login page that redirects the user to UmmahPass for authorization. The link should go to:

https://ummahpass.io/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yoursite.com/auth/ummahpass/callback
  &response_type=code
  &scope=profile points membership
  &state=RANDOM_CSRF_TOKEN

Handle the Callback: Exchange Code for Token

When the user authorizes your app, UmmahPass redirects them back to your redirect URI with a code parameter. Your server must exchange that code for an access token by making a POST request.

See Complete Flow Walkthrough below for the exact request.

Fetch the User's Profile

Use the access token from Step 4 to call GET /api/user. This returns the user's name, email, membership tier, points balance, and verification status.

See User Data Response below for the full field list.

Create or Update the User in Your Database

Use the user data to find or create an account in your own database. Match on email (or store the id as ummahpass_id). Then log the user into your site.

Done. Your users can now log in with UmmahPass.

2. Complete Flow Walkthrough (Any Language)

This is the universal guide. These are plain HTTP requests. They work the same whether you're using PHP, Python, Node, Ruby, Go, or anything else. Copy and paste the curl commands to test.

Redirect User to Authorization

Your login button sends the user's browser to this URL (all one line, broken up here for readability):

https://ummahpass.io/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyoursite.com%2Fauth%2Fummahpass%2Fcallback&response_type=code&scope=profile%20points%20membership&state=abc123random

The state parameter should be a random string you store in the user's session. You will verify it in the callback to prevent CSRF attacks.

User Authorizes Your App

The user sees a consent screen on UmmahPass asking them to authorize your app. After they approve, UmmahPass redirects them back to your redirect URI:

https://yoursite.com/auth/ummahpass/callback?code=def50200abc123...longrandomstring&state=abc123random

Verify that state matches what you stored in the session before proceeding.

Exchange Authorization Code for Access Token

Your server makes a POST request to exchange the authorization code for an access token. This must be a server-side request (never expose your client secret in client-side code).

curl -X POST https://ummahpass.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://yoursite.com/auth/ummahpass/callback" \
  -d "code=def50200abc123...longrandomstring"

Response (200 OK):

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciO...long_jwt_token",
  "refresh_token": "def50200a8b9c7d...refresh_token_string"
}

Store the access_token securely. It expires in one year. The refresh_token can be used to get a new access token when needed.

Fetch User Data

Use the access token to get the user's profile:

curl https://ummahpass.io/api/user \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciO...long_jwt_token" \
  -H "Accept: application/json"

Response (200 OK):

{
  "id": 42,
  "name": "Ashraf Mahmoud",
  "email": "ashraf@example.com",
  "email_verified_at": "2026-01-15T10:30:00.000000Z",
  "is_pro": true,
  "is_verified_muslim": true,
  "points_balance": 5000,
  "points_multiplier": 1.0,
  "referral_code": "ASHRAF01",
  "country_code": "US",
  "region": "California",
  "created_at": "2026-01-01T00:00:00.000000Z"
}

Which fields are returned depends on the scopes your token was granted. See OAuth Scopes below.

Create/Update User and Log In

Use the response data to find or create a user in your own database (match on email or id). Store the id as ummahpass_id for future reference. Then create a session for the user on your site. That is it -- the integration is complete.

3. User Data Response

When you call GET /api/user with a valid access token, you receive a JSON object with these fields:

Field	Type	Scope	Description
id	integer	profile	Unique UmmahPass user ID
name	string	profile	User's display name
email	string	email	User's email address
email_verified_at	string\|null	email	When email was verified (null if unverified)
is_pro	boolean	membership	Pro membership status
is_verified_muslim	boolean	profile	Verified Muslim community member
points_balance	integer	points	Current UmmahPoints balance
points_multiplier	float	points	Points earning rate (0.5, 1.0, or 2.0)
referral_code	string	profile	User's referral code
country_code	string\|null	profile	2-letter ISO country code (e.g., "US")
region	string\|null	profile	State or region
created_at	string	profile	Account creation timestamp (ISO 8601)

4. OAuth Scopes

Scopes control what data your app can access. Request only the scopes you need. The /api/user response is scope-aware -- it only returns fields matching the granted scopes.

Scope	Gives You
profile	id, name, is_verified_muslim, referral_code, country_code, region, created_at
email	email, email_verified_at
points	points_balance, points_multiplier
membership	is_pro (Pro/Max membership status)

Recommended default: profile email points membership (most integrations need all four).

5. Testing Your Integration

Testing Locally

OAuth requires a publicly accessible redirect URI. If you are developing locally, use a tool like ngrok to create a tunnel:

# Start ngrok on your local port
ngrok http 8000

# ngrok gives you a URL like: https://abc123.ngrok.io
# Use that as your redirect URI: https://abc123.ngrok.io/auth/ummahpass/callback
# Email us with this redirect URI for testing (we can update it for production later)

Common Errors

invalid_client 401

Your Client ID or Client Secret is wrong. Double-check both values. Make sure there are no extra spaces.

invalid_request - redirect_uri mismatch 400

The redirect URI in your request does not match what we have on file. It must be an exact match, including trailing slashes, https vs http, and port numbers. Email us if you need to update it.

invalid_grant 400

The authorization code has expired (codes are single-use and expire in 30 seconds) or was already used. Redirect the user to authorize again.

401 Unauthenticated on /api/user

Your access token is missing, expired, or malformed. Make sure the Authorization header is Bearer YOUR_TOKEN (with the space after Bearer).

State mismatch / CSRF error

The state parameter in the callback does not match what you stored in the session. Make sure you store the state before redirecting, and verify it when the user comes back.

How to Verify It Works

1. Click your "Login with UmmahPass" button. You should be redirected to ummahpass.io.
2. Log in (or create an account) on UmmahPass. You should see a consent screen asking to authorize your app.
3. Click Authorize. You should be redirected back to your site.
4. Check your database. You should have a new user record with the UmmahPass user's name and email.
5. You should be logged into your site. Try accessing a protected page to confirm the session is active.

If any step fails, check the Common Errors section above or email us at salaam@ummahpass.io.

6. Code Examples (Optional Reference)

The flow walkthrough above is all you need. These are just copy-paste examples if your stack matches one below. UmmahPass is standard OAuth 2.0, so any OAuth library in any language will work.

WordPress (miniOrange OAuth Plugin)

The easiest option. No code required -- just install the plugin and fill in the fields.

1. Install "OAuth Single Sign On" by miniOrange from the WordPress plugin directory.
2. Go to miniOrange OAuth → Configure OAuth and select "Custom OAuth 2.0 App".

3. Fill in the fields exactly like this:

Plugin Field	Value
App Name	`UmmahPass`
Client ID	`YOUR_CLIENT_ID`
Client Secret	`YOUR_CLIENT_SECRET`
Authorize Endpoint	`https://ummahpass.io/oauth/authorize`
Access Token Endpoint	`https://ummahpass.io/oauth/token`
Get User Info Endpoint	`https://ummahpass.io/api/user`
Scope	`profile points membership`

4. Under Attribute Mapping, set:

WordPress Field	Maps to
Username	`email`
Email	`email`
First Name	`name`

5. Save. A "Login with UmmahPass" button will appear on your WordPress login page.

Laravel

Use Laravel's built-in HTTP client. No Socialite provider needed.

1. Add credentials to config/services.php:

// config/services.php
'ummahpass' => [
    'client_id' => env('UMMAHPASS_CLIENT_ID'),
    'client_secret' => env('UMMAHPASS_CLIENT_SECRET'),
    'redirect' => env('UMMAHPASS_REDIRECT_URI'),
],

2. Add to your .env:

UMMAHPASS_CLIENT_ID=your_client_id
UMMAHPASS_CLIENT_SECRET=your_client_secret
UMMAHPASS_REDIRECT_URI=https://yoursite.com/auth/ummahpass/callback

3. Add routes to routes/web.php:

Route::get('/auth/ummahpass', [UmmahPassController::class, 'redirect']);
Route::get('/auth/ummahpass/callback', [UmmahPassController::class, 'callback']);

4. Create the controller. See full code example below.

PHP

PHP (Generic)

Use the league/oauth2-client package with Composer.

1. Install: composer require league/oauth2-client
2. Create a GenericProvider with the 3 UmmahPass URLs.
3. Handle the redirect and callback. See full code example below.

Node.js (Express + Passport)

Use passport-oauth2 with Express.

1. Install: npm install passport passport-oauth2
2. Configure the OAuth2 strategy with UmmahPass URLs.
3. Add the auth routes. See full code example below.

Python (Django + requests-oauthlib)

Use requests-oauthlib for Django or Flask projects.

1. Install: pip install requests-oauthlib
2. Add UMMAHPASS_CLIENT_ID, UMMAHPASS_CLIENT_SECRET, and UMMAHPASS_REDIRECT_URI to your settings.py or environment variables.
3. Add URL patterns and views. See full code example below.

Laravel Controller

<?php

namespace App\Http\Controllers\Auth;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
use App\Models\User;

class UmmahPassController
{
    // Step 1: Redirect user to UmmahPass
    public function redirect(Request $request)
    {
        $request->session()->put('ummahpass_state', $state = bin2hex(random_bytes(16)));

        $query = http_build_query([
            'client_id' => config('services.ummahpass.client_id'),
            'redirect_uri' => config('services.ummahpass.redirect'),
            'response_type' => 'code',
            'scope' => 'profile points membership',
            'state' => $state,
        ]);

        return redirect('https://ummahpass.io/oauth/authorize?' . $query);
    }

    // Step 2: Handle callback from UmmahPass
    public function callback(Request $request)
    {
        // Verify state to prevent CSRF
        if ($request->state !== $request->session()->pull('ummahpass_state')) {
            abort(403, 'Invalid state parameter.');
        }

        // Exchange code for token
        $response = Http::asForm()->post('https://ummahpass.io/oauth/token', [
            'grant_type' => 'authorization_code',
            'client_id' => config('services.ummahpass.client_id'),
            'client_secret' => config('services.ummahpass.client_secret'),
            'redirect_uri' => config('services.ummahpass.redirect'),
            'code' => $request->code,
        ]);

        if ($response->failed()) {
            return redirect('/login')->with('error', 'Authentication failed.');
        }

        $token = $response->json('access_token');

        // Fetch user data
        $userData = Http::withToken($token)
            ->get('https://ummahpass.io/api/user')
            ->json();

        // Find or create user
        $user = User::updateOrCreate(
            ['email' => $userData['email']],
            [
                'name' => $userData['name'],
                'ummahpass_id' => $userData['id'],
            ]
        );

        auth()->login($user);
        return redirect('/dashboard');
    }
}

PHP (Generic) with league/oauth2-client

<?php

require 'vendor/autoload.php';
session_start();

$provider = new League\OAuth2\Client\Provider\GenericProvider([
    'clientId'                => 'YOUR_CLIENT_ID',
    'clientSecret'            => 'YOUR_CLIENT_SECRET',
    'redirectUri'             => 'https://yoursite.com/callback',
    'urlAuthorize'            => 'https://ummahpass.io/oauth/authorize',
    'urlAccessToken'          => 'https://ummahpass.io/oauth/token',
    'urlResourceOwnerDetails' => 'https://ummahpass.io/api/user',
    'scopes'                  => 'profile points membership',
]);

// Step 1: Redirect to authorization
if (!isset($_GET['code'])) {
    $authUrl = $provider->getAuthorizationUrl();
    $_SESSION['oauth2state'] = $provider->getState();
    header('Location: ' . $authUrl);
    exit;
}

// Step 2: Verify state
if (empty($_GET['state']) || $_GET['state'] !== $_SESSION['oauth2state']) {
    unset($_SESSION['oauth2state']);
    exit('Invalid state');
}

// Step 3: Exchange code for token
$token = $provider->getAccessToken('authorization_code', [
    'code' => $_GET['code']
]);

// Step 4: Fetch user data
$user = $provider->getResourceOwner($token);
$userData = $user->toArray();

// $userData contains: id, name, email, is_pro, is_verified_muslim,
// points_balance, points_multiplier, referral_code, etc.

Node.js (Express + Passport)

const passport = require('passport');
const OAuth2Strategy = require('passport-oauth2');

passport.use('ummahpass', new OAuth2Strategy({
    authorizationURL: 'https://ummahpass.io/oauth/authorize',
    tokenURL: 'https://ummahpass.io/oauth/token',
    clientID: process.env.UMMAHPASS_CLIENT_ID,
    clientSecret: process.env.UMMAHPASS_CLIENT_SECRET,
    callbackURL: 'https://yoursite.com/auth/ummahpass/callback',
    scope: 'profile points membership'
}, async (accessToken, refreshToken, profile, done) => {
    // Fetch user data from UmmahPass
    const response = await fetch('https://ummahpass.io/api/user', {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    });
    const userData = await response.json();

    // Find or create user in your database
    const user = await User.findOrCreate({
        where: { email: userData.email },
        defaults: {
            name: userData.name,
            ummahpassId: userData.id,
        }
    });

    done(null, user);
}));

// Routes
app.get('/auth/ummahpass', passport.authenticate('ummahpass'));
app.get('/auth/ummahpass/callback',
    passport.authenticate('ummahpass', { failureRedirect: '/login' }),
    (req, res) => res.redirect('/dashboard')
);

Python (Django)

# views.py
import os
from requests_oauthlib import OAuth2Session
from django.shortcuts import redirect
from django.contrib.auth import login
from .models import User

CLIENT_ID = os.environ['UMMAHPASS_CLIENT_ID']
CLIENT_SECRET = os.environ['UMMAHPASS_CLIENT_SECRET']
REDIRECT_URI = os.environ['UMMAHPASS_REDIRECT_URI']

AUTHORIZE_URL = 'https://ummahpass.io/oauth/authorize'
TOKEN_URL = 'https://ummahpass.io/oauth/token'
USER_URL = 'https://ummahpass.io/api/user'


def ummahpass_login(request):
    """Step 1: Redirect user to UmmahPass"""
    oauth = OAuth2Session(CLIENT_ID, redirect_uri=REDIRECT_URI,
                          scope=['profile', 'points', 'membership'])
    auth_url, state = oauth.authorization_url(AUTHORIZE_URL)
    request.session['oauth_state'] = state
    return redirect(auth_url)


def ummahpass_callback(request):
    """Step 2: Handle callback, exchange code, fetch user"""
    oauth = OAuth2Session(CLIENT_ID, redirect_uri=REDIRECT_URI,
                          state=request.session['oauth_state'])

    # Exchange code for token
    token = oauth.fetch_token(
        TOKEN_URL,
        client_secret=CLIENT_SECRET,
        authorization_response=request.build_absolute_uri(),
    )

    # Fetch user data
    resp = oauth.get(USER_URL)
    user_data = resp.json()

    # Find or create user
    user, created = User.objects.update_or_create(
        email=user_data['email'],
        defaults={
            'username': user_data['email'],
            'first_name': user_data['name'],
            'ummahpass_id': user_data['id'],
        }
    )

    login(request, user)
    return redirect('/dashboard')

Add to urls.py:

# urls.py
from . import views

urlpatterns = [
    path('auth/ummahpass/', views.ummahpass_login, name='ummahpass_login'),
    path('auth/ummahpass/callback/', views.ummahpass_callback, name='ummahpass_callback'),
]

7. Benefits of Integration

Single Sign-On

Users log in once and access all Ummah ecosystem sites. No separate registration needed.

Verified Users

Know which users are verified Muslims. Build trust in your community platform.

Points Integration

Award UmmahPoints for user activities on your platform. Points work across the entire ecosystem.

Need Help?

Email us at salaam@ummahpass.io and we will help you get set up.

Include your site URL, the error message you are seeing, and your platform. We typically respond within 24 hours.

Contact Developer Support

Developer Brief

What you need

What you get back

3 URLs to configure

On This Page

1. Quick Start Checklist

Get Your OAuth Credentials

Set Up Your Redirect URI

Add a "Login with UmmahPass" Button

Handle the Callback: Exchange Code for Token

Fetch the User's Profile

Create or Update the User in Your Database

2. Complete Flow Walkthrough (Any Language)

Redirect User to Authorization

User Authorizes Your App

Exchange Authorization Code for Access Token

Response (200 OK):

Fetch User Data

Response (200 OK):

Create/Update User and Log In

3. User Data Response

4. OAuth Scopes

5. Testing Your Integration

Testing Locally

Common Errors

How to Verify It Works

6. Code Examples (Optional Reference)

WordPress (miniOrange OAuth Plugin)

Laravel

PHP (Generic)

Node.js (Express + Passport)

Python (Django + requests-oauthlib)

Laravel Controller

PHP (Generic) with league/oauth2-client

Node.js (Express + Passport)

Python (Django)

7. Benefits of Integration

Single Sign-On

Verified Users

Points Integration

Need Help?