# Authorisation
All Pay.io API requests must be authenticated with three headers:
Header
Description
X-API-Key
Your unique merchant API key from Merchant Console.
X-API-Nonce
Unique identifier (UUID) per request.
X-API-Signature
RSA-SHA256 signature generated using your private key.
***
### Creating a Public and Private Key
Merchants must provide **Pay.io** with a **public key** during onboarding.
**Requirements:**
* At least 2048 bits
* PEM format
You can use the following code sample to generate the public key and private key.
{% code title="Example in Python" overflow="wrap" lineNumbers="true" %}
```python
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.primitives import serialization
# Generate 2048-bit private key
private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
# Serialize keys to PEM
pem_private = private_key.private_bytes(
encoding=serialization.Encoding.PEM,
format=serialization.PrivateFormat.TraditionalOpenSSL,
encryption_algorithm=serialization.NoEncryption()
)
pem_public = private_key.public_key().public_bytes(
encoding=serialization.Encoding.PEM,
format=serialization.PublicFormat.SubjectPublicKeyInfo
)
```
{% endcode %}
***
### Creating a Merchant Signature
Every API request must be signed.
#### Steps
1. **Generate a nonce** — Secure random string, at least 16 chars
`# Example in Python def generate_nonce(): return str(uuid.uuid4())`
2. **Build canonical string** using the rules:
1. The request’s signature is calculated over this **exact** concatenation (no delimiters):
`METHOD + PATH + NONCE + QUERY + BODY`
3. **Sign** with your merchant’s private key using **RSA-SHA256**.
4. **Base64-encode** the signature.
5. **Send** it in the `X-API-Signature` header
#### Example Python
{% code overflow="wrap" lineNumbers="true" %}
```python
def generate_auth_headers(method, path, query_string, body, api_signing_secret):
# 1. Generate unique nonce (UUID4 string)
nonce = str(uuid.uuid4())
# 2. Build the canonical signing data
signing_data = method + path + nonce + query_string + (body or "")
# 3. Create the HMAC-SHA256 signature
signature = hmac.new(
key=api_signing_secret.encode("utf-8"),
msg=signing_data.encode("utf-8"),
digestmod=hashlib.sha256
).hexdigest()
# 4. Return headers
return {
"X-API-Nonce": nonce,
"X-API-Signature": signature
}
# Example usage
headers = generate_auth_headers(
method="POST",
path="/v1/payments",
query_string="order_id=123",
body='{"amount":100,"currency":"USD"}',
api_signing_secret="my_secret_key"
)
```
{% endcode %}
***
### Example Authenticated Request
{% code overflow="wrap" lineNumbers="true" %}
```bash
curl --location 'https://gateway.stage.pay.io/v1/user/withdraw' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'X-API-Nonce: 123e4567-e89b-12d3-a456-426614174000' \
--header 'X-API-Signature: BASE64_SIGNATURE' \
--data '{"amount":"100.50","currency_id":"c872e749-fd56-533e-b01f-de87ae38e7f1","wallet_address":"0x123...","user_reference_id":"hub_player_2"}'
```
{% endcode %}
***
### Error Codes
#### Error Type: `missing signature`
Status Code**:** `401`
Response Body:
```json
{ "message": "missing signature" }
```
#### Error Type: `missing api key`
Status Code: `401`
Response Body:
```json
{ "message": "missing api key" }
```
#### Error Type: `invalid api key`
Status Code: `401`
Response Body:
```json
{ "message": "invalid api key" }
```
#### Error Type: `nonce too short`
Status Code: `400`
Response Body:
```json
{ "message": "nonce too short" }
```
#### **Error Type: `nonce already used`**
Status Code: `401`
Response Body:
```json
{ "message": "invalid request signature" }
```
#### **Error Type: `invalid nonce`**
* **Status Code: 400**
* **Response Body:**
```json
{ "message": "invalid nonce" }
```
#### **Error Type: `missing nonce`**
Status Code**:** `401`
Response Body:
```json
{ "message": "missing nonce" }
```
#### **Error Type: `timestamp expired`**
Status Code: `401`
Response Body:
```json
{ "message": "timestamp expired" }
```
#### **Error Type: `multiple nonces`**
Status Code: `401`
Response Body:
```json
{ "message": "multiple nonces" }
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.pay.io/api-reference/core-concepts/authorisation.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.