---
title: Authentication
description: API keys, scopes, and environment separation
---

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:

```bash
Authorization: Bearer sk_live_your_secret_key
```

### Key Types

| Environment | Prefix     | Use Case                |
| ----------- | ---------- | ----------------------- |
| Production  | `sk_live_` | Real transactions       |
| Sandbox     | `sk_test_` | Testing and development |

### Getting Your Keys

1. Log in at [my.rizpay.app](https://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

| Scope                  | Description              |
| ---------------------- | ------------------------ |
| `read_balance`         | View account balance     |
| `read_transactions`    | View transaction history |
| `view_products`        | List and view products   |
| `purchase_airtime`     | Purchase airtime         |
| `purchase_data`        | Purchase data plans      |
| `purchase_electricity` | Purchase electricity     |
| `purchase_cable_tv`    | Purchase cable TV        |
| `manage_webhooks`      | Manage webhook endpoints |

### 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:

```json
{
  "status": {
    "code": 403,
    "message": "Forbidden"
  },
  "error": {
    "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:

```json
{
  "status": {
    "code": 403,
    "message": "Forbidden"
  },
  "error": {
    "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:

```json
{
  "status": {
    "code": 403,
    "message": "Forbidden"
  },
  "error": {
    "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

| Action  | Effect                          | Reversible |
| ------- | ------------------------------- | ---------- |
| Disable | Temporarily blocks the key      | Yes        |
| Revoke  | Permanently invalidates the key | No         |

### Multiple Keys

Create separate keys for:

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

## Authentication Errors

| Code                      | Description     | Solution                 |
| ------------------------- | --------------- | ------------------------ |
| `AUTHENTICATION_REQUIRED` | No key provided | Add Authorization header |
| `INVALID_CREDENTIALS`     | Key is invalid  | Check key is correct     |
| `TOKEN_REVOKED`           | Key was revoked | Generate new key         |
| `TOKEN_EXPIRED`           | Key has expired | Generate new key         |

## Code Examples

### Node.js

```javascript
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

```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

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

## Next Steps

- [Error Handling](/docs/getting-started/errors) - Handle authentication errors
- [Sandbox Testing](/docs/core-concepts/sandbox) - Test your integration
- [Rate Limiting](/docs/core-concepts/rate-limiting) - Understand rate limits