API key management

API keys authenticate all requests to the QairoPay API. This guide covers everything you need to manage them safely.

Create a key

1. Open the QairoPay dashboard and navigate to Developer → API Keys.
2. Click Create API key.
3. Enter a name (e.g., Production backend, POS reader).
4. Select the appropriate scope (see Key scopes below).
5. Click Create — the key is displayed in plaintext exactly once.

Copy the key immediately. Once you close the modal, the full key is never shown again. If you lose it, revoke it and create a new one.

Key prefixes

The prefix tells you which environment the key targets:

Prefix	Environment	Base URL
qp_live_	Production	https://api.qairopay.com
qp_test_	Sandbox	https://sandbox-api.qairopay.com

A live key used against the sandbox URL (or vice versa) will receive a 401 Unauthorized response. The SDK picks the correct base URL automatically from the key prefix — you only need to override baseUrl if you’re using a custom mirror.

Initialize the client

Pass the key via an environment variable — never hardcode it in source:

export QAIROPAY_API_KEY="qp_live_..."

TypeScript:

import { QairoPay } from "@qairopay/sdk";

const qp = new QairoPay({ apiKey: process.env.QAIROPAY_API_KEY! });

Python:

import os
from qairopay import QairoPay

qp = QairoPay(api_key=os.environ["QAIROPAY_API_KEY"])

Go:

import "github.com/qairopay/go-sdk"

client, err := qairopay.NewClient(os.Getenv("QAIROPAY_API_KEY"))

Key scopes

Scopes limit what a key can do:

Scope	Use case
pass:scan	POS adapters that only need to verify pass scans. Restricts the key to scan-related endpoints.
(full access)	Default — access to all endpoints the tenant is entitled to use.

Additional scopes are reserved for future use. When creating a key for a POS integration, use pass:scan so that a leaked key has minimal blast radius.

Rotation procedure

Rotate a key without downtime:

1. Create a new key with the same scope as the old one.
2. Update all dependent systems — services, environment variables, secrets managers — to use the new key.
3. Verify that traffic is flowing normally with the new key (check the dashboard’s request log or your own metrics).
4. Revoke the old key: Developer → API Keys → ⋯ → Revoke.

Don’t skip step 3. Revoking before verifying can cause an outage if any system still uses the old key.

Sandbox usage

Use sandbox keys (qp_test_) for all development and testing. Sandbox data is isolated from production — passes issued in the sandbox do not appear in the live dashboard and vice versa.

To switch an existing integration from sandbox to live, swap the QAIROPAY_API_KEY environment variable for a live key. The SDK automatically adjusts the base URL. No code changes required.