Authentication

Overview

The FLEX SSO API uses OAuth 2.0 Authorization Code Flow to securely authenticate customers and grant access to their wallets. This flow ensures that customer credentials never pass through your servers.

Authentication Flow

Customer Login

User provides PayTag and password

Request Auth Code

Your backend calls /sso/auth-code to get authorization code

Redirect Customer

Redirect user to the returned URL containing the auth code

Exchange for Token

Extract auth code from redirect and exchange it for a customer JWT token

Make Authenticated Requests

Use the JWT token in the Authorization: Bearer header for all wallet operations

Required Headers

For Partner-Only Endpoints

These endpoints only require partner credentials (PayTag creation, auth flow):

string

required

Your partner client identifier

string

required

Your partner API key

For Customer-Authenticated Endpoints

These endpoints require both partner credentials AND customer token (wallet operations):

string

required

Your partner client identifier

string

required

Your partner API key

string

required

Customer JWT token in format: Bearer {token}

Step 1: Request Authorization Code

When a customer wants to log in, send their credentials to get an authorization code.

curl --request POST \
  --url 'https://staging-api.yourflexpay.com/v2/sso/auth-code?scope=profile' \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key' \
  --data '{
    "paytag": "@johndoe",
    "password": "customer_password"
  }'

const response = await fetch(
  'https://staging-api.yourflexpay.com/v2/sso/auth-code?scope=profile',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-client-id': process.env.PARTNER_CLIENT_ID,
      'x-api-key': process.env.PARTNER_API_KEY
    },
    body: JSON.stringify({
      paytag: '@johndoe',
      password: 'customer_password'
    })
  }
);

const redirectUrl = await response.text();
console.log('Redirect URL:', redirectUrl);
// Output: https://your-app.com/callback?auth-code=abc123xyz

import requests

response = requests.post(
    'https://staging-api.yourflexpay.com/v2/sso/auth-code',
    params={'scope': 'profile'},
    headers={
        'Content-Type': 'application/json',
        'x-client-id': os.getenv('PARTNER_CLIENT_ID'),
        'x-api-key': os.getenv('PARTNER_API_KEY')
    },
    json={
        'paytag': '@johndoe',
        'password': 'customer_password'
    }
)

redirect_url = response.text
print(f'Redirect URL: {redirect_url}')

Response: A redirect URL containing the authorization code

https://your-app.com/callback?auth-code=abc123xyz

The redirect URL is configured during partner onboarding. Contact support to set or update your redirect URLs.

Step 2: Exchange Auth Code for Token

After redirecting the customer and receiving the auth code in your callback endpoint, exchange it for a JWT token.

curl --request GET \
  --url 'https://staging-api.yourflexpay.com/v2/sso/token?auth-code=abc123xyz' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key'

// Extract auth code from redirect URL
const urlParams = new URLSearchParams(window.location.search);
const authCode = urlParams.get('auth-code');

// Exchange for token (backend)
const response = await fetch(
  `https://staging-api.yourflexpay.com/v2/sso/token?auth-code=${authCode}`,
  {
    headers: {
      'x-client-id': process.env.PARTNER_CLIENT_ID,
      'x-api-key': process.env.PARTNER_API_KEY
    }
  }
);

const customerToken = await response.text();
// Store this token securely (session, encrypted cookie, etc.)

# Extract auth code from redirect
auth_code = request.args.get('auth-code')

# Exchange for token
response = requests.get(
    f'https://staging-api.yourflexpay.com/v2/sso/token',
    params={'auth-code': auth_code},
    headers={
        'x-client-id': os.getenv('PARTNER_CLIENT_ID'),
        'x-api-key': os.getenv('PARTNER_API_KEY')
    }
)

customer_token = response.text
# Store in session
session['flex_token'] = customer_token

Response: A JWT token for the authenticated customer

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Store the customer token securely! Never expose it in client-side JavaScript or logs. Use server-side sessions or encrypted cookies.

Step 3: Make Authenticated Requests

Use the customer token to access wallet features:

const response = await fetch(
  'https://staging-api.yourflexpay.com/v2/sso/wallet',
  {
    headers: {
      'x-client-id': process.env.PARTNER_CLIENT_ID,
      'x-api-key': process.env.PARTNER_API_KEY,
      'Authorization': `Bearer ${customerToken}`
    }
  }
);

const wallet = await response.json();
console.log('Balance:', wallet.Balance);

response = requests.get(
    'https://staging-api.yourflexpay.com/v2/sso/wallet',
    headers={
        'x-client-id': os.getenv('PARTNER_CLIENT_ID'),
        'x-api-key': os.getenv('PARTNER_API_KEY'),
        'Authorization': f'Bearer {customer_token}'
    }
)

wallet = response.json()
print(f"Balance: {wallet['Balance']}")

Complete Implementation Example

Here’s a complete OAuth flow implementation:

const express = require('express');
const app = express();

// Step 1: Login endpoint
app.post('/auth/flex/login', async (req, res) => {
  const { paytag, password } = req.body;

  try {
    const response = await fetch(
      'https://staging-api.yourflexpay.com/v2/sso/auth-code?scope=profile',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-client-id': process.env.PARTNER_CLIENT_ID,
          'x-api-key': process.env.PARTNER_API_KEY
        },
        body: JSON.stringify({ paytag, password })
      }
    );

    const redirectUrl = await response.text();
    res.json({ redirectUrl });
  } catch (error) {
    res.status(401).json({ error: 'Authentication failed' });
  }
});

// Step 2: Callback endpoint
app.get('/auth/flex/callback', async (req, res) => {
  const authCode = req.query['auth-code'];

  if (!authCode) {
    return res.status(400).json({ error: 'Missing auth code' });
  }

  try {
    const response = await fetch(
      `https://staging-api.yourflexpay.com/v2/sso/token?auth-code=${authCode}`,
      {
        headers: {
          'x-client-id': process.env.PARTNER_CLIENT_ID,
          'x-api-key': process.env.PARTNER_API_KEY
        }
      }
    );

    const customerToken = await response.text();

    // Store in session
    req.session.flexToken = customerToken;

    // Redirect to wallet dashboard
    res.redirect('/wallet/dashboard');
  } catch (error) {
    res.status(401).json({ error: 'Token exchange failed' });
  }
});

// Example authenticated endpoint
app.get('/wallet/balance', async (req, res) => {
  const token = req.session.flexToken;

  if (!token) {
    return res.status(401).json({ error: 'Not authenticated' });
  }

  const response = await fetch(
    'https://staging-api.yourflexpay.com/v2/sso/wallet',
    {
      headers: {
        'x-client-id': process.env.PARTNER_CLIENT_ID,
        'x-api-key': process.env.PARTNER_API_KEY,
        'Authorization': `Bearer ${token}`
      }
    }
  );

  const wallet = await response.json();
  res.json({ balance: wallet.Balance });
});

from flask import Flask, request, session, redirect, jsonify
import requests
import os

app = Flask(__name__)
app.secret_key = 'your-secret-key'

FLEX_BASE_URL = 'https://staging-api.yourflexpay.com/v2'
PARTNER_CLIENT_ID = os.getenv('PARTNER_CLIENT_ID')
PARTNER_API_KEY = os.getenv('PARTNER_API_KEY')

# Step 1: Login endpoint
@app.route('/auth/flex/login', methods=['POST'])
def flex_login():
    data = request.json
    paytag = data.get('paytag')
    password = data.get('password')

    try:
        response = requests.post(
            f'{FLEX_BASE_URL}/sso/auth-code',
            params={'scope': 'profile'},
            headers={
                'Content-Type': 'application/json',
                'x-client-id': PARTNER_CLIENT_ID,
                'x-api-key': PARTNER_API_KEY
            },
            json={'paytag': paytag, 'password': password}
        )

        redirect_url = response.text
        return jsonify({'redirectUrl': redirect_url})
    except Exception as e:
        return jsonify({'error': 'Authentication failed'}), 401

# Step 2: Callback endpoint
@app.route('/auth/flex/callback')
def flex_callback():
    auth_code = request.args.get('auth-code')

    if not auth_code:
        return jsonify({'error': 'Missing auth code'}), 400

    try:
        response = requests.get(
            f'{FLEX_BASE_URL}/sso/token',
            params={'auth-code': auth_code},
            headers={
                'x-client-id': PARTNER_CLIENT_ID,
                'x-api-key': PARTNER_API_KEY
            }
        )

        customer_token = response.text
        session['flex_token'] = customer_token

        return redirect('/wallet/dashboard')
    except Exception as e:
        return jsonify({'error': 'Token exchange failed'}), 401

# Example authenticated endpoint
@app.route('/wallet/balance')
def wallet_balance():
    token = session.get('flex_token')

    if not token:
        return jsonify({'error': 'Not authenticated'}), 401

    response = requests.get(
        f'{FLEX_BASE_URL}/sso/wallet',
        headers={
            'x-client-id': PARTNER_CLIENT_ID,
            'x-api-key': PARTNER_API_KEY,
            'Authorization': f'Bearer {token}'
        }
    )

    wallet = response.json()
    return jsonify({'balance': wallet['Balance']})

Token Management

Token Lifecycle

Expiration: Customer tokens have a limited lifespan (check with support for exact duration)
Refresh: Currently, tokens must be re-obtained through the auth flow
Storage: Store securely server-side, never in client-side storage

Best Practices

Use HTTPS only - Never transmit tokens over unencrypted connections

Server-side storage - Store tokens in encrypted server-side sessions

Token validation - Check for 401 errors and prompt re-authentication

Logout handling - Clear tokens from session when user logs out

Error Responses

401 - Unauthorized

Cause: Invalid credentials or expired/invalid tokenSolution:

For auth-code: Verify customer PayTag and password are correct
For token exchange: Verify auth code is valid and not expired
For authenticated requests: Token may be expired, prompt re-login

400 - Bad Request

Cause: Missing or invalid parametersSolution: Check that all required fields are included and properly formatted

404 - Not Found

Cause: Customer PayTag doesn’t existSolution: Guide user to create a PayTag using the PayTag creation flow

Security Considerations

Never store passwords! The OAuth flow ensures passwords never hit your database. Only store the customer token.

Use Environment Variables

Store partner credentials in environment variables

Implement Rate Limiting

Prevent brute force attacks on login endpoints

Log Security Events

Monitor failed authentication attempts

HTTPS Required

Always use HTTPS in production

Next Steps

PayTag Creation

Learn how to create new customer accounts

Integration Guide

Build complete wallet features

Wallet API

Explore wallet management endpoints

Transactions API

Process payments and transfers

API Reference

OAuth Flow Endpoints

Get Authorization Code

POST /sso/auth-code - Authenticate customer and get authorization code

Exchange Token

GET /sso/token - Exchange authorization code for customer JWT token

PayTag Creation Endpoints

Verify PayTag

GET /sso/verify-tag - Check if a PayTag is available

Initiate Creation

POST /sso/create-tag - Start PayTag creation with BVN verification

Send OTP

GET /sso/{session}/otp - Send OTP for verification

Validate OTP

POST /sso/{session}/otp - Validate OTP code

Complete Creation

POST /sso/create-tag/{session}/complete - Create PayTag

Get Session

GET /sso - Get PayTag creation session payload

Required Headers

Partner Authentication (PayTag Creation):

x-client-id: Your partner ID
x-api-key: Your partner API key

Customer Authentication (Wallet Operations):

x-client-id: Your partner ID
x-api-key: Your partner API key
Authorization: Bearer {customer_token}

Complete API Specification: View the full SSO OpenAPI Spec for detailed schemas and all endpoint specifications.

Wallet SSO

Merchant

Partner

IDAAS

Authentication

Overview

Authentication Flow

Required Headers

For Partner-Only Endpoints

For Customer-Authenticated Endpoints

Step 1: Request Authorization Code

Step 2: Exchange Auth Code for Token

Step 3: Make Authenticated Requests

Complete Implementation Example

Token Management

Token Lifecycle

Best Practices

Error Responses

Security Considerations

Use Environment Variables

Implement Rate Limiting

Log Security Events

HTTPS Required

Next Steps

PayTag Creation

Integration Guide

Wallet API

Transactions API

API Reference

OAuth Flow Endpoints

Get Authorization Code

Exchange Token

PayTag Creation Endpoints

Verify PayTag

Initiate Creation

Send OTP

Validate OTP

Complete Creation

Get Session

Required Headers

​Overview

​Authentication Flow

​Required Headers

​For Partner-Only Endpoints

​For Customer-Authenticated Endpoints

​Step 1: Request Authorization Code

​Step 2: Exchange Auth Code for Token

​Step 3: Make Authenticated Requests

​Complete Implementation Example

​Token Management

​Token Lifecycle

​Best Practices

​Error Responses

​Security Considerations

Use Environment Variables

Implement Rate Limiting

Log Security Events

HTTPS Required

​Next Steps

PayTag Creation

Integration Guide

Wallet API

Transactions API

​API Reference

​OAuth Flow Endpoints

Get Authorization Code

Exchange Token

​PayTag Creation Endpoints

Verify PayTag

Initiate Creation

Send OTP

Validate OTP

Complete Creation

Get Session

​Required Headers

Overview

Authentication Flow

Required Headers

For Partner-Only Endpoints

For Customer-Authenticated Endpoints

Step 1: Request Authorization Code

Step 2: Exchange Auth Code for Token

Step 3: Make Authenticated Requests

Complete Implementation Example

Token Management

Token Lifecycle

Best Practices

Error Responses

Security Considerations

Next Steps

API Reference

OAuth Flow Endpoints

PayTag Creation Endpoints

Required Headers