Authentication

Fatoorah Pay uses API Key authentication for all API requests. This guide explains how to authenticate your requests and manage your API keys securely.

Overview

API keys provide a simple and secure way to authenticate your requests without requiring user login. Each API key is associated with your Fatoorah Pay account and inherits all account permissions.

API Key Format

API keys follow this format:

Test Keys: sk_test_xxxxxxxxxxxxxx (32 random characters)
Live Keys: sk_live_xxxxxxxxxxxxxx (32 random characters)

Example Keys

Test:  sk_test_Hvybntilj0x3mxP-x0xNH4d94Q7o8ugQJtqEhmM_g3k
Live:  sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd

Authentication Method

Include your API key in the X-API-KEY header of every request:

X-API-KEY: sk_test_your_key_here

Example Request

curl -X POST https://pay.fatoorah.ai/api/v1/payment-links \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sk_test_your_key_here" \
  -d '{
    "isLive": false,
    "data": {
      "amount_cents": 10000,
      "full_name": "Test Customer",
      "phone_number": "+966501234567",
      "description": "Test Payment"
    }
  }'

Generating API Keys

Via Dashboard (Recommended)

Log in to Fatoorah Pay Dashboard
Navigate to Account > API Keys
Click Generate New Key
Select environment:
- TEST - For development and testing
- LIVE - For production
Enter a descriptive name (e.g., "Production Server", "Development Environment")
Copy the key immediately - it's shown only once!
Store it securely

Via API (Using JWT Authentication)

If you're using the Client Frontend collection with JWT authentication:

# First, login to get JWT token
curl -X POST https://pay.fatoorah.ai/account/auth/login \
  -H "Content-Type: application/json" \
  -H "X-AUTH-PROVIDER: ACCOUNT" \
  -d '{
    "email": "your@email.com",
    "password": "your_password"
  }'

# Then create API key
curl -X POST https://pay.fatoorah.ai/api/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-AUTH-PROVIDER: ACCOUNT" \
  -d '{
    "name": "My API Key",
    "isLive": false
  }'

Environment Restrictions

API keys are environment-specific and must match the isLive flag in your requests:

API Key Type	`isLive: false`	`isLive: true`
`sk_test_xxx`	✅ Allowed	❌ REJECTED
`sk_live_xxx`	❌ REJECTED	✅ Allowed

Error Response

If you attempt to use a test key with isLive: true (or vice versa):

{
  "success": false,
  "error": {
    "code": "AK-403",
    "message": "API key environment does not match requested operation mode. Test keys cannot be used for live transactions and vice versa.",
    "timestamp": "2025-12-04T10:00:00Z",
    "path": "/api/v1/payment-links"
  }
}

Security Best Practices

✅ DO

Store keys in environment variables:

export FATOORAH_API_KEY="sk_test_your_key_here"

Use different keys per environment:
- Separate keys for development, staging, and production
- Use test keys for development
- Use live keys only in production
Rotate keys regularly:
- Rotate every 90 days (recommended)
- Rotate immediately if compromised
Monitor key usage:
- Check dashboard for key activity
- Set up alerts for unusual activity
Use secrets management:
- AWS Secrets Manager
- HashiCorp Vault
- Azure Key Vault
- Environment-specific config files
Restrict key access:
- Only share keys with authorized team members
- Use different keys for different services

❌ DON'T

Never commit keys to version control:

# BAD - Don't do this
git add .env  # Contains API keys
git commit -m "Add config"

Never hardcode keys in source code:

// BAD - Don't do this
const apiKey = "sk_test_abc123...";

Never share keys via email/Slack:
- Use secure channels for key sharing
- Revoke and regenerate if accidentally shared
Never use live keys in development:
- Always use test keys for testing
- Keep live keys for production only
Never expose keys in client-side code:
- API keys are for server-to-server only
- Frontend apps should use JWT authentication

Never log keys in application logs:

// BAD - Don't do this
console.log("API Key:", apiKey);

Key Rotation

Regularly rotating API keys is a security best practice.

Rotation Process

Generate new key:
- Create new key in dashboard
- Use same environment (test/live)

Update application:

# Update environment variable
export FATOORAH_API_KEY="sk_test_new_key_here"

Deploy with new key:
- Deploy updated configuration
- Verify new key works

Test new key:

curl -X GET https://pay.fatoorah.ai/api/v1/transactions \
  -H "X-API-KEY: sk_test_new_key_here"

Revoke old key:
- Go to dashboard
- Find old key
- Click "Revoke"

Zero-Downtime Rotation

For production systems, rotate keys without downtime:

Generate new key
Update configuration (but don't deploy yet)
Deploy with both keys temporarily
Verify new key works
Remove old key from configuration
Revoke old key in dashboard

Error Responses

Invalid API Key (401)

{
  "success": false,
  "error": {
    "code": "AK-401",
    "message": "Invalid API key provided.",
    "timestamp": "2025-12-04T10:00:00Z",
    "path": "/api/v1/payment-links"
  }
}

Causes:

Key is incorrect or mistyped
Key has been revoked
Key has expired (if expiration is enabled)

Solution:

Verify key is copied correctly
Check key hasn't been revoked
Generate a new key if needed

Missing API Key (401)

{
  "success": false,
  "error": {
    "code": "AK-401",
    "message": "API key is required.",
    "timestamp": "2025-12-04T10:00:00Z",
    "path": "/api/v1/payment-links"
  }
}

Solution:

Ensure X-API-KEY header is included
Check header name is correct (case-sensitive)

Environment Mismatch (403)

{
  "success": false,
  "error": {
    "code": "AK-403",
    "message": "API key environment does not match requested operation mode.",
    "timestamp": "2025-12-04T10:00:00Z",
    "path": "/api/v1/payment-links"
  }
}

Solution:

Use test key with isLive: false
Use live key with isLive: true

Key Management

Viewing Keys

Log in to dashboard
Navigate to Account > API Keys
View all active keys
See key metadata (name, created date, last used)

Revoking Keys

Go to Account > API Keys
Find the key to revoke
Click Revoke
Confirm revocation

Note: Revoked keys cannot be restored. You'll need to generate a new key.

Key Limits

Maximum 100 API keys per account
Both test and live keys count toward the limit

Code Examples

Node.js

const axios = require('axios');

const fatoorahClient = axios.create({
  baseURL: 'https://pay.fatoorah.ai',
  headers: {
    'X-API-KEY': process.env.FATOORAH_API_KEY,  // From environment variable
    'Content-Type': 'application/json'
  }
});

// Make authenticated request
const response = await fatoorahClient.post('/api/v1/payment-links', {
  isLive: false,
  data: {
    amount_cents: 10000,
    full_name: 'Test Customer',
    phone_number: '+966501234567',
    description: 'Test Payment'
  }
});

Python

import os
import requests

api_key = os.getenv('FATOORAH_API_KEY')  # From environment variable

headers = {
    'X-API-KEY': api_key,
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://pay.fatoorah.ai/api/v1/payment-links',
    headers=headers,
    json={
        'isLive': False,
        'data': {
            'amount_cents': 10000,
            'full_name': 'Test Customer',
            'phone_number': '+966501234567',
            'description': 'Test Payment'
        }
    }
)

PHP

<?php
$apiKey = getenv('FATOORAH_API_KEY');  // From environment variable

$ch = curl_init('https://pay.fatoorah.ai/api/v1/payment-links');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-KEY: ' . $apiKey,
        'Content-Type: application/json'
    ],
        CURLOPT_POSTFIELDS => json_encode([
            'isLive' => false,
            'data' => [
            'amount_cents' => 10000,
            'full_name' => 'Test Customer',
            'phone_number' => '+966501234567',
            'description' => 'Test Payment'
        ]
    ])
]);

$response = curl_exec($ch);
curl_close($ch);
?>

Next Steps

Getting Started Guide - Complete integration tutorial
Test Credentials - Test API keys and cards
Payment Links - Create shareable payment links
Webhooks - Set up webhook notifications