Authentication

Secure your API requests with bearer token authentication and learn best practices for API key management.

API Key Authentication

The HexAI Payment Gateway uses API keys for authentication. Each client account receives unique API keys for both testing and production environments.

API Key Types

Making Authenticated Requests

HTTP Header

Include your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer hexai_your_api_key_here

cURL Example

curl https://hpg.hexai.gm/api/v1/collections/initiate \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "GMD",
    "client_reference": "ORDER-12345",
    "success_url": "https://yoursite.com/success",
    "error_url": "https://yoursite.com/cancel"
  }'

JavaScript Example

const axios = require('axios');

const apiKey = process.env.HEXAI_API_KEY; // sk_test_* for testing

const response = await axios.post(
  'https://hpg.hexai.gm/api/v1/collections/initiate',
  {
    amount: "100.00",
    currency: 'GMD',
    client_reference: 'ORDER-12345',
    success_url: 'https://yoursite.com/success',
    error_url: 'https://yoursite.com/cancel'
  },
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  }
);

Python Example

import os
import requests

api_key = os.environ['HEXAI_API_KEY']  # sk_test_* for testing

response = requests.post(
    'https://hpg.hexai.gm/api/v1/collections/initiate',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'amount': '100.00',
        'currency': 'GMD',
        'client_reference': 'ORDER-12345',
        'success_url': 'https://yoursite.com/success',
        'error_url': 'https://yoursite.com/cancel'
    }
)

Dashboard Authentication

The admin and client dashboards use JWT-based session authentication. After logging in, a secure httpOnly cookie stores your session token.

Client Dashboard Login

POST /auth/client/login
Content-Type: application/json

{
  "email": "client@example.com",
  "password": "your_password"
}

Admin Dashboard Login

POST /auth/admin/login
Content-Type: application/json

{
  "email": "admin@hexai.gm",
  "password": "admin_password"
}

Security Best Practices

1. Keep API Keys Secret

• Never commit API keys to version control
• Use environment variables to store keys
• Never expose keys in client-side code (JavaScript, mobile apps)
• Don't log API keys in application logs

2. Use Environment Variables

# .env file
HEXAI_API_KEY=hexai_your_api_key_here
WEBHOOK_SECRET=your_webhook_secret_here

// Load from environment
require('dotenv').config();

const apiKey = process.env.HEXAI_API_KEY;
const webhookSecret = process.env.WEBHOOK_SECRET;

3. Rotate API Keys Regularly

Contact the HexAI admin team to rotate your API key if:

• You suspect it has been compromised
• An employee with access leaves your organization
• As part of regular security maintenance (recommended every 90 days)

4. Use HTTPS Only

Always make API requests over HTTPS to prevent interception of your API key. The HexAI API only accepts HTTPS requests.

5. Implement Rate Limiting

Implement rate limiting in your application to prevent abuse and reduce the impact if your API key is compromised.

6. Monitor API Usage

Regularly review your API usage in the client dashboard. Look for:

• Unusual spike in requests
• Requests from unexpected IP addresses
• Failed authentication attempts

Error Responses

401 Unauthorized

Returned when the API key is missing, invalid, or expired.

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Returned when the API key is valid but doesn't have permission for the requested resource.

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

API Key Scopes

Currently, API keys have full access to all payment operations for your client account. Future versions will support scoped keys with limited permissions (e.g., read-only, collections-only).

Testing Authentication

You can verify your API key is working correctly with a simple test request:

curl https://hpg.hexai.gm/api/client/profile \
  -H "Authorization: Bearer hexai_your_api_key_here"

Success response:

{
  "id": "clx123abc",
  "name": "Your Business Name",
  "businessPhone": "+220300000000",
  "businessEmail": "billing@yourbusiness.com",
  "status": "ACTIVE"
}

Webhook Authentication

Webhooks use HMAC-SHA256 signatures for authentication instead of API keys. See the Webhook Integration Guide for details.

Two-Factor Authentication (2FA)

Dashboard accounts support optional 2FA using Time-based One-Time Passwords (TOTP). Enable 2FA in your dashboard settings for enhanced security.

Enabling 2FA

1. Navigate to Settings → Security in your dashboard
2. Click "Enable Two-Factor Authentication"
3. Scan the QR code with an authenticator app (Google Authenticator, Authy, etc.)
4. Enter the verification code to confirm setup
5. Save your recovery codes in a secure location

IP Whitelisting

Enterprise clients can restrict API access to specific IP addresses. Contact the HexAI admin team to configure IP whitelisting for your account.

Session Management

Dashboard Sessions

• Sessions expire after 24 hours of inactivity
• Sessions are invalidated when you log out
• Only one active session per account (logging in elsewhere invalidates previous sessions)

Logout

POST /auth/logout
Cookie: session_token=...

Compliance

The HexAI Payment Gateway follows industry security standards:

• All data encrypted in transit with TLS 1.3
• API keys encrypted at rest using AES-256
• Regular security audits and penetration testing
• PCI DSS Level 1 compliance (in progress)

Getting Help

If you believe your API key has been compromised or need assistance with authentication:

• Email: security@hexai.gm
• Emergency: Contact your account manager directly

Next Steps

• Explore the API Reference
• Learn about Webhook Integration
• Check the Frequently Asked Questions