Integrate FAAX XAUTH CONNECT
into your product

📖 Overview #

FAAX XAUTH CONNECT acts as an Identity Provider: a single trusted service that manages user identities across multiple third-party applications. Your app never stores passwords — instead, you rely on FAAX to authenticate and return a verified user identity.

How it works

Your app receives only the KYC fields that were explicitly authorized by the FAAX administrator. No extra data is ever exposed.

⚡ Quick Start #

Get your first authenticated user in under 10 minutes.

1. Get your credentials from FAAX

   Contact your FAAX administrator to register your app. You'll receive a client_id, client_secret, and api_key, and your authorized scopes will be configured.
2. Add the login button to your app

   Redirect users to the FAAX login page with your client_id and redirect_uri.
3. Handle the callback

   FAAX redirects back to your app with a token parameter. Call api_verify_token from your backend to exchange it for user data.
4. Create the user session in your app

   Use the returned user object (and optionally the kyc object) to identify the user and grant access.

<!-- Step 2: Add to your app's login page -->
<a href="https://faax.xcompanyee.com/xauth/
  ?client_id=faax_YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback">
  Login with FAAX
</a>

// Step 3: Handle callback at https://yourapp.com/callback
$token = $_GET['token'];

$response = file_get_contents('https://faax.xcompanyee.com/xauth/?action=api_verify_token', false,
  stream_context_create(['http' => [
    'method'  => 'POST',
    'header'  => 'X-Api-Key: YOUR_API_KEY\r\nContent-Type: application/x-www-form-urlencoded',
    'content' => 'token=' . urlencode($token)
  ]])
);

$data = json_decode($response, true);
// $data['user']['email']  → verified email
// $data['kyc']['full_name'] → authorized KYC fields

🔑 Credentials #

Each registered app receives three credentials with different purposes:

Authentication methods

You can authenticate API requests in two ways:

# Method 1 — Header (recommended)
POST /xauth/?action=api_verify_token
X-Api-Key: your_api_key_here

# Method 2 — Query parameter
POST /xauth/?action=api_verify_token&api_key=your_api_key_here

🔗 SSO Login Flow #

The SSO flow redirects users to FAAX for authentication. The user sees a consent screen showing exactly which data your app will receive, then logs in.

1. Initiate login

Redirect the user to the FAAX login URL:

GET https://faax.xcompanyee.com/xauth/
  ?client_id=faax_YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &state=OPTIONAL_CSRF_TOKEN

2. Receive the callback

After the user authenticates, FAAX redirects to your redirect_uri with these parameters:

# Success
https://yourapp.com/callback?token=abc123...&email=user@example.com

# User denied consent
https://yourapp.com/callback?error=access_denied

3. Verify the token (backend)

Exchange the token immediately from your server — tokens expire in 5 minutes and are single-use.

👤 Register Users #

Pre-register users into FAAX from your backend. If the email already exists in FAAX, the user is simply linked to your app and a notification email is sent.

{
  "success": true,
  "user_id": 42,
  "message": "User created and linked."
}

✅ Verify Token #

The most important endpoint. Exchanges the one-time SSO token for verified user identity and authorized KYC data.

{
  "valid": true,
  "user": {
    "id":     42,
    "email":  "user@example.com",
    "name":   "Jane Doe",
    "status": "verified"
  },
  "kyc": {
    // Only fields your app is authorized to receive
    "full_name":       "Jane Mary Doe",
    "document_number": "123.456.789-00",
    "verified_at":     "2024-11-01 10:22:00"
  }
}

📋 User Endpoints #

🔒 KYC Scopes #

The FAAX admin controls exactly which KYC fields each app can receive. You cannot request more data than what has been authorized for your app.

⚠ Sensitive — fields marked as sensitive require explicit justification when requesting access from the FAAX admin.

📦 KYC Response Format #

The kyc object inside api_verify_token response contains only the fields your app is authorized to see. Always code defensively:

$data = json_decode($response, true);

if (!$data['valid']) {
  // Token invalid or already used
  die('Authentication failed');
}

$user = $data['user'];          // always present
$kyc  = $data['kyc'] ?? [];   // may be absent if user has no KYC

$fullName  = $kyc['full_name']       ?? null;
$docNumber = $kyc['document_number'] ?? null;

⚠️ Error Codes #

🛡 Security Best Practices #

• ✓ Always verify tokens server-side. Never accept the email from the callback URL as proof of identity — always call api_verify_token from your backend.
• ✓ Use the state parameter to prevent CSRF attacks. Generate a random token, store it in the session, and verify it matches when you receive the callback.
• ✓ Keep secrets out of version control. Use environment variables ($_ENV['FAAX_API_KEY']) or a secrets manager instead of hardcoding credentials.
• ✓ Register your exact redirect URI. Must start with https://. The FAAX system rejects any callback that doesn't match your registered URI.

💬 FAQ #

How long is a token valid?

Tokens are valid for 5 minutes and can only be used once. Verify it immediately after receiving the callback.

What if the user has no KYC data?

The kyc field will be absent from the response. Your code should always use $data['kyc'] ?? [] to default to an empty array.

Can I request more KYC fields later?

Yes — contact your FAAX administrator. They can update your app's authorized scopes at any time. The change takes effect immediately on the next SSO login.

What is the redirect_uri format requirement?

The URI must begin with https:// and exactly match what was registered. The FAAX system automatically normalizes URIs (adds https://, removes duplicates, strips trailing slashes) during registration.

Can I have multiple redirect URIs?

Currently one base URI per app is supported. Subdirectories of your registered base URI are allowed (e.g., https://app.com/auth/callback if your registered URI is https://app.com).

What happens if login fails 3 times?

Accounts are temporarily locked for 15 minutes after 3 failed attempts to protect users from brute force attacks.