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

# Authentication

> How to authenticate with the Dancity merchant API

## Merchant API key

Every **VAS** (`/api/v1`) request must include:

```http theme={null}
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
channel: API
```

> [!WARNING]
>
> Your API key can spend wallet balance and purchase services on behalf of the linked account. **Never expose it in client-side code, public repositories, or logs.** Store it only in server-side environment variables.

### Example (merchant)

```bash cURL theme={null}
curl -sS -X POST "https://api.dancity.app/api/v1/cable/validate" \
  -H "Authorization: Bearer dcy_live_xxxx..." \
  -H "Content-Type: application/json" \
  -H "channel: API" \
  -d '{"smartcardNumber":"1234567890","cablename":"DSTV"}'
```

```javascript Node.js / fetch theme={null}
await fetch(
  "https://api.dancity.app/api/v1/data/buy",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
      "Content-Type": "application/json",
      channel: "API",
    },
    body: JSON.stringify({
      plan: "PLAN_ID",
      phone: "08012345678",
      wallettype: "main",
      pin: "1234",
    }),
  },
);
```

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

requests.post(
    "https://api.dancity.app/api/v1/airtime/buy",
    headers={
        "Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}",
        "Content-Type": "application/json",
        "channel": "API",
    },
    json={
        "product": "MTN Airtime",
        "phone": "08012345678",
        "amount": 500,
        "pin": "1234",
    },
    timeout=60,
)
```

***

## IP allowlist (merchant keys)

Restrict your API key to specific IPs or CIDR ranges from your [API key page](https://dancity.app/profile/api-key). Adding or changing entries requires OTP verification.

> [!NOTE]
>
> **An empty IP allowlist blocks all traffic.** Add at least one IP or CIDR before calling the VAS (merchant) API.

| Format | Example |
| - | - |
| IPv4 | `203.0.113.5` |
| IPv6 | `2001:db8::1` |
| IPv4 CIDR | `192.168.1.0/24` |
| IPv6 CIDR | `2001:db8::/32` |

Up to **20** entries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.