​
Overview

HOST Pay uses API Key authentication for all API requests. Each application has separate credentials for Test Mode and Live Mode to ensure secure development and production workflows.

​
API Credentials

Every application has two sets of credentials:

Test Mode Credentials

For development and testing - uses sandbox services

Live Mode Credentials

For production - processes real transactions
Each credential set consists of:
  • API Key: Identifies your application
  • Secret Key: Authenticates your requests
Never expose your secret keys in client-side code, public repositories, or logs. Always keep them secure on your server.

​
Making Authenticated Requests

Include both keys in the request headers: 
curl --request GET \
  --url https://hpay-api.host-sl.com/api/v1/users/ \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY'

​
Credential Management

​
Generating Credentials

1

Access Dashboard

Log in to the HOST Pay dashboard
2

Select Application

Navigate to your application
3

Credentials Section

Go to the API Credentials section
4

Generate Keys

Click “Generate New Credential” for Test or Live mode

​
Credential Lifecycle

  • Active: Credential is valid and can authenticate requests
  • Disabled: Credential has been revoked and cannot be used
  • Expired: Credential has reached its expiration date (if set)

​
Best Practices

Store credentials in environment variables, never hardcode them:
export HOST_PAY_API_KEY="your_api_key"
export HOST_PAY_SECRET_KEY="your_secret_key"

import os

api_key = os.getenv("HOST_PAY_API_KEY")
secret_key = os.getenv("HOST_PAY_SECRET_KEY")
Generate new credentials periodically and revoke old ones:
  1. Generate new credentials
  2. Update your application
  3. Test with new credentials
  4. Revoke old credentials
Maintain separate credentials for:
  • Development
  • Staging
  • Production
Check the last_used timestamp in the dashboard to identify unused or compromised credentials.

​
Security Considerations

​
Do’s ✅

  • ✅ Store credentials in environment variables
  • ✅ Use HTTPS for all API requests
  • ✅ Rotate keys regularly
  • ✅ Revoke compromised keys immediately
  • ✅ Use separate credentials per environment
  • ✅ Monitor credential usage

​
Don’ts ❌

  • ❌ Commit keys to version control
  • ❌ Share keys via email or chat
  • ❌ Log keys in application logs
  • ❌ Use production keys in development
  • ❌ Expose keys in client-side code
  • ❌ Reuse keys across applications

​
Handling Authentication Errors

​
401 Unauthorized

This error occurs when credentials are missing or invalid: 
{
  "detail": "Invalid application credentials"
}
Common causes:
  • Missing api-key or secret-key header
  • Incorrect credential values
  • Using revoked credentials
  • Using expired credentials
Solution:
  • Verify your credentials in the dashboard
  • Check for typos in the header names
  • Ensure credentials haven’t been revoked

​
403 Forbidden

This error occurs when you don’t have permission: 
{
  "detail": "You do not have permission to access this resource"
}
Common causes:
  • Trying to access resources from another application
  • Using test credentials to access live resources (or vice versa)
  • Accessing admin-only endpoints with application credentials
Solution:
  • Use the correct credentials for the environment
  • Verify you’re accessing resources in your application’s schema

​
Example: Complete Authentication Flow

import os
import requests

class HostPayClient:
    def __init__(self, api_key=None, secret_key=None):
        self.api_key = api_key or os.getenv("HOST_PAY_API_KEY")
        self.secret_key = secret_key or os.getenv("HOST_PAY_SECRET_KEY")
        self.base_url = "https://hpay-api.host-sl.com/api/v1"
        
        if not self.api_key or not self.secret_key:
            raise ValueError("API credentials are required")
    
    def _get_headers(self):
        return {
            "api-key": self.api_key,
            "secret-key": self.secret_key,
            "Content-Type": "application/json"
        }
    
    def make_request(self, method, endpoint, **kwargs):
        url = f"{self.base_url}{endpoint}"
        headers = self._get_headers()
        
        response = requests.request(
            method=method,
            url=url,
            headers=headers,
            **kwargs
        )
        response.raise_for_status()
        return response.json()
    
    def create_user(self, name, email, phone_number):
        return self.make_request(
            "POST",
            "/users/",
            json={
                "name": name,
                "email": email,
                "phone_number": phone_number
            }
        )

# Usage
client = HostPayClient()
user = client.create_user(
    name="Jane Doe",
    email="jane@example.com",
    phone_number="+23279123456"
)
print(f"Created user: {user['id']}")

​
Testing Authentication

You can verify your credentials are working: 
curl --request GET \
  --url https://hpay-api.host-sl.com/api/v1/users/ \
  --header 'api-key: YOUR_API_KEY' \
  --header 'secret-key: YOUR_SECRET_KEY'

​
Need Help?

If you’re experiencing authentication issues:

Check Credentials

Verify your credentials in the dashboard

Contact Support

Reach out if issues persist