Authentication

Payscribe API requests authenticate with an API key in the Authorization Bearer header. Keep that key on infrastructure you control; your browser and mobile client should call your server, not Payscribe with an API key.

Deployment configurationSecret manager or server environmentPAYSCRIBE_API_KEY is available to the backend only↓

1 · ClientBrowser or mobile appCalls your backend with user-safe dataNo Payscribe API key

HTTPS→

2 · Secure boundaryYour backendReads its environment and builds the requestAuthorization: Bearer pk_...

HTTPS→

3 · PayscribePayscribe APIAuthenticates the key and returns API dataResponse to backend

Security rule: your backend returns only the data the client needs. It never returns the API key, raw authorization header, or sensitive wallet configuration.

Never expose an API key

Do not put pk_... keys in frontend code, mobile apps, Git repositories, browser storage, screenshots, URLs, or support tickets. Rotate a key immediately if it is exposed.

Keys and environments

Create and manage API keys in Settings → API Keys in the Payscribe dashboard.

Credential	Typical prefix	Environment	Where to use it
Sandbox API key	ps_pk_test_...	https://sandbox.payscribe.ng/api/v1	Your server during development and test
Production API key	ps_pk_live_...	https://api.payscribe.ng/api/v1	Your production server only
Webhook secret	ps_test_... / ps_live_...	Matches the webhook environment	Verifies the HMAC signature; it never goes in an API Authorization header

The dashboard may label pk_... credentials as public keys, but the current direct API authenticates business operations with them. Keep all direct API calls on your backend and protect the key accordingly. Production requests also require a configured server IP allowlist.

Make an authenticated request

Set PAYSCRIBE_API_KEY in your server environment, then send it as a Bearer token. Do not hardcode the key in these examples.

cURL

curl https://sandbox.payscribe.ng/api/v1/my-account/balances \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY"

Node.js

const response = await fetch('https://sandbox.payscribe.ng/api/v1/my-account/balances', {
  headers: {Authorization: `Bearer ${process.env.PAYSCRIBE_API_KEY}`},
});

if (!response.ok) throw new Error(`Payscribe request failed: ${response.status}`);
const result = await response.json();

Python

import os
import requests

response = requests.get(
    'https://sandbox.payscribe.ng/api/v1/my-account/balances',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}"},
    timeout=20,
)
response.raise_for_status()

Go

request, err := http.NewRequest(http.MethodGet,
  "https://sandbox.payscribe.ng/api/v1/my-account/balances", nil)
if err != nil { log.Fatal(err) }
request.Header.Set("Authorization", "Bearer "+os.Getenv("PAYSCRIBE_API_KEY"))

response, err := http.DefaultClient.Do(request)
if err != nil { log.Fatal(err) }
defer response.Body.Close()

Handle authentication failures safely

Authentication errors must be useful to your engineering team without leaking credentials to users or logs.

Example authentication error

{
  "status": false,
  "description": "Invalid API key",
  "status_code": 401
}

Status	Meaning	Safe response
401	The key is missing, invalid, expired, or paired with the wrong environment.	Stop and check your server configuration. Do not retry automatically.
403	The key is authenticated but does not have permission for the operation.	Check dashboard access and contact support if the product should be enabled.

Log the HTTP status, endpoint, and a safe request reference where one exists. Never log the Authorization header or the raw API key.

Rotate keys without downtime

Plan key rotation as an operational change, not a last-minute emergency:

1. Create a replacement key in the dashboard.
2. Update the API key in your deployment environment.
3. Deploy and confirm sandbox or production health checks with the new key.
4. Revoke the old key once traffic is confirmed on the replacement.

If a key may have been exposed, rotate it immediately and review application logs and deployment history.

Continue building

Next task	Use this guide
Verify a sandbox request	Quickstart
Test a full workflow safely	Sandbox testing
Secure event delivery	Webhooks
Understand every endpoint	API authentication reference