Authentication

Learn how to authenticate API requests using API keys with scoped permissions.

API Keys

Every API request requires a valid API key in the Authorization header:

Authorization: Bearer sk_live_your_secret_key

Key Types

Getting Your Keys

1. Log in at my.rizpay.app
2. Go to Settings > API Keys
3. Click Create New Key
4. Select environment and scopes
5. Copy the key immediately (shown only once!)

Key Security

• Never expose keys in client-side code
• Never commit keys to version control
• Use environment variables to store keys
• Regenerate keys if compromised
• Use separate keys for different applications

Scopes

Scopes control what actions an API key can perform. Select only the scopes you need.

Available Scopes

Example: Minimal Scope for Airtime

If you only need to purchase airtime:

view_products      - To list airtime products
purchase_airtime   - To make purchases
read_transactions  - To check purchase status

Insufficient Scope Error

If you call an endpoint without the required scope:

{
  "status": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This action requires the 'purchase_data' scope"
  }
}

Environments

Production and sandbox are completely isolated.

Production

Base URL: https://my.rizpay.app/api/partners/v1
API Keys: sk_live_*

• Real transactions
• Real charges
• Affects customer accounts

Sandbox

Base URL: https://my.rizpay.app/api/partners/sandbox/v1
API Keys: sk_test_*

• Test transactions only
• No real charges
• Mock responses

Environment Mismatch

Using the wrong key type returns an error:

{
  "status": {
    "code": "ENVIRONMENT_MISMATCH",
    "message": "Sandbox API keys can only access sandbox endpoints"
  }
}

IP Whitelisting

Optionally restrict API access to specific IP addresses.

Setup

When creating or editing an API key:

1. Enable IP whitelisting
2. Enter allowed IPs (comma-separated)
3. Save the key

Format

192.168.1.1, 10.0.0.0/8, 2001:db8::1

Supports:

• Single IPv4 addresses
• IPv4 CIDR ranges
• IPv6 addresses

Blocked Request

Requests from non-whitelisted IPs return:

{
  "status": {
    "code": "IP_NOT_ALLOWED",
    "message": "Request IP is not in the allowed list"
  }
}

Key Management

Regenerate Secret

If your key is compromised:

1. Go to Settings > API Keys
2. Click the key
3. Click Regenerate Secret
4. Update your application immediately

The old secret is invalidated instantly.

Disable vs Revoke

Multiple Keys

Create separate keys for:

• Different environments (dev, staging, production)
• Different applications
• Different team members
• Different permission levels

Authentication Errors

Code Examples

Node.js

const API_KEY = process.env.RIZPAY_API_KEY;

const response = await fetch(
  "https://my.rizpay.app/api/partners/v1/account/balance",
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  }
);

Python

import os
import requests

API_KEY = os.environ['RIZPAY_API_KEY']

response = requests.get(
    'https://my.rizpay.app/api/partners/v1/account/balance',
    headers={'Authorization': f'Bearer {API_KEY}'}
)

cURL

curl -X GET \
  -H "Authorization: Bearer $RIZPAY_API_KEY" \
  https://my.rizpay.app/api/partners/v1/account/balance

Next Steps

• Error Handling - Handle authentication errors
• Sandbox Testing - Test your integration
• Rate Limiting - Understand rate limits