> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate your API requests

## API Key Authentication

The OneClickDz Flexy API uses API key authentication. All requests must include your API key in the request header.

### Header Format

```http theme={null}
X-Access-Token: YOUR_API_KEY
```

<Note>
  The header name is `X-Access-Token` (not `Authorization`). Make sure you use
  the correct header name.
</Note>

## API Key Types

You have access to two types of API keys:

<CardGroup cols={2}>
  <Card title="Sandbox Key" icon="flask">
    **Purpose**: Testing and development - No real balance deduction - Simulated
    responses - Special test numbers available - Safe for development
  </Card>

  <Card title="Production Key" icon="rocket">
    **Purpose**: Live transactions - Real balance deduction - Live operator
    integration - Production-ready - Use with caution
  </Card>
</CardGroup>

## Generating API Keys

<Steps>
  <Step title="Login to Dashboard">
    Visit [enterprise.oneclickdz.com](https://enterprise.oneclickdz.com/api-keys) and login to your account
  </Step>

  <Step title="Navigate to Settings">Go to Settings → API Configuration</Step>

  <Step title="Generate Keys">
    Click "Generate API Key" for both Sandbox and Production environments
  </Step>

  <Step title="Save Securely">
    Copy and store your keys in a secure location. You won't be able to see them
    again.
  </Step>
</Steps>

## Validating Your API Key

Test your API key using the validate endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.oneclickdz.com/v3/validate \
    --header 'X-Access-Token: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.oneclickdz.com/v3/validate", {
    headers: {
      "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
    },
  });

  const data = await response.json();

  if (data.success) {
    console.log("API key is valid!");
    console.log("Account:", data.data.username);
    console.log("Key type:", data.data.apiKey.type);
  } else {
    console.error("API key validation failed:", data.error);
  }
  ```

  ```python Python theme={null}
  import requests
  import os

  response = requests.get(
      'https://api.oneclickdz.com/v3/validate',
      headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
  )

  data = response.json()

  if data['success']:
      print('API key is valid!')
      print(f"Account: {data['data']['username']}")
      print(f"Key type: {data['data']['apiKey']['type']}")
  else:
      print(f"API key validation failed: {data['error']}")
  ```

  ```php PHP theme={null}
  <?php
  $apiKey = getenv('ONECLICKDZ_API_KEY');
  $ch = curl_init("https://api.oneclickdz.com/v3/validate");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: " . $apiKey]);
  $response = curl_exec($ch);
  $data = json_decode($response, true);

  if ($data['success']) {
      echo "API key is valid!\n";
      echo "Account: " . $data['data']['username'] . "\n";
      echo "Key type: " . $data['data']['apiKey']['type'] . "\n";
  } else {
      echo "API key validation failed: " . json_encode($data['error']) . "\n";
  }
  ?>
  ```
</CodeGroup>

### Successful Response

```json theme={null}
{
  "success": true,
  "data": {
    "username": "+213665983439",
    "apiKey": {
      "key": "ea27b376-9f5c-4b09-883f-1b96cd7b541c",
      "isEnabled": true,
      "type": "SANDBOX",
      "allowedips": [],
      "scope": "READ-WRITE"
    }
  }
}
```

## API Key Properties

Your API key includes the following properties:

| Property     | Description                    |
| ------------ | ------------------------------ |
| `key`        | Your unique API key identifier |
| `isEnabled`  | Whether the key is active      |
| `type`       | `SANDBOX` or `PRODUCTION`      |
| `allowedips` | IP whitelist                   |
| `scope`      | `READ-WRITE` or `READ-ONLY`    |

## IP Whitelisting

For enhanced security, you can restrict your API keys to specific IP addresses. Each environment (Production and Sandbox) has its own independent IP whitelist.

<Steps>
  <Step title="Go to API Settings">
    Navigate to Settings → API Configuration in your dashboard
  </Step>

  <Step title="Add IP Addresses">
    Enter the specific IP addresses for each environment: - **Production IP
    Whitelist**: Controls access for your production API key - **Sandbox IP
    Whitelist**: Controls access for your sandbox API key - Leave empty to allow
    all IP addresses
  </Step>

  <Step title="Save Changes">
    Click "Update IP Whitelist" to apply the changes
  </Step>
</Steps>

<Warning>
  When IP whitelist contains addresses, only those specific IPs will be allowed.
  Requests from other IPs will be rejected with a 403 error.
</Warning>

### IP Whitelist Format

Add specific IP addresses to the whitelist, one per line:

* `203.0.113.45` - Allows only this specific IP address
* `198.51.100.23` - Another specific IP address

<Tip>
  Leave the whitelist empty to allow all IP addresses (default behavior). Add
  IPs to enable restrictions.
</Tip>

## Key Scopes

API keys can have different access levels:

### READ-WRITE (Default)

Full access to all operations:

* View balance and transactions
* Send top-ups
* Place orders
* Check status

### READ-ONLY

Limited to read operations:

* View balance and transactions
* Check top-up status
* List orders
* Cannot create new transactions

<Tip>
  Use READ-ONLY keys for reporting dashboards or analytics tools that shouldn't
  modify data.
</Tip>

## Error Responses

### 400 - Missing API Key

```json theme={null}
{
  "success": false,
  "error": {
    "code": "MISSING_ACCESS_TOKEN",
    "message": "Access token is required"
  },
  "requestId": "req_abc123"
}
```

### 401 - Invalid API Key

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid",
    "details": {
      "attemptsLeft": 3
    }
  },
  "requestId": "req_abc123"
}
```

<Warning>
  After 5 failed authentication attempts, your IP will be temporarily blocked
  for 15 minutes.
</Warning>

### 403 - IP Not Whitelisted

```json theme={null}
{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Your IP address 203.0.113.45 is not whitelisted for this PRODUCTION API key. Add your IP to the whitelist at  https://app.oneclickdz.com/#/settings"
  },
  "requestId": "req_abc123"
}
```

<Tip>
  The error response includes your current IP address and the environment
  (SANDBOX or PRODUCTION) to help you quickly identify which whitelist needs
  updating.
</Tip>

### 403 - IP Blocked

```json theme={null}
{
  "success": false,
  "error": {
    "code": "IP_BLOCKED",
    "message": "Your IP has been temporarily blocked due to too many invalid attempts"
  },
  "requestId": "req_abc123"
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store Keys Securely" icon="lock">
    * Never commit API keys to version control
    * Use environment variables or secret management systems
    * Rotate keys periodically
    * Use different keys for different environments
  </Accordion>

  {" "}

  <Accordion title="Use HTTPS Only" icon="shield-halved">
    * Always use HTTPS endpoints - Never send API keys over HTTP - Verify SSL
      certificates
  </Accordion>

  {" "}

  <Accordion title="Implement IP Whitelisting" icon="list-check">
    * Whitelist only necessary IP addresses - Use specific IPs instead of broad
      ranges - Update whitelist when infrastructure changes
  </Accordion>

  {" "}

  <Accordion title="Monitor API Usage" icon="chart-line">
    * Track API key usage regularly - Set up alerts for unusual activity - Review
      access logs - Revoke compromised keys immediately
  </Accordion>

  <Accordion title="Limit Key Scope" icon="eye-slash">
    * Use READ-ONLY keys where possible
    * Create separate keys for different services
    * Implement least privilege principle
  </Accordion>
</AccordionGroup>

## Key Rotation

It's recommended to rotate your API keys periodically:

<Steps>
  <Step title="Generate New Key">Create a new API key from your dashboard</Step>

  <Step title="Update Application">
    Deploy your application with the new key
  </Step>

  <Step title="Verify">Test that the new key works correctly</Step>

  <Step title="Revoke Old Key">
    Once verified, revoke the old key from your dashboard
  </Step>
</Steps>

<Tip>Rotate keys at least every 90 days for enhanced security.</Tip>

## Need Help?

If you're having authentication issues:

1. Verify your API key is correct
2. Check that you're using the correct header name (`X-Access-Token`)
3. Ensure your IP is whitelisted (if enabled)
4. Check the API status at [status.oneclickdz.com](https://status.oneclickdz.com)
5. Contact support at [support@oneclickdz.com](mailto:support@oneclickdz.com)