Authentication
How Xtopay authenticates API requests using Client ID and Client Secret.
Overview
Every Xtopay API request must be authenticated. Xtopay uses HTTP Basic Authentication with your Client ID and Client Secret — a credential pair you obtain from the dashboard.
Authorization: Basic <base64(client_id:client_secret)>Credentials
| Credential | Format | Where to find it |
|---|---|---|
| Client ID | cid_test_... or cid_live_... | Dashboard → Settings → API Credentials |
| Client Secret | csk_test_... or csk_live_... | Dashboard → Settings → API Credentials |
The Client ID identifies your application. The Client Secret is a secret known only to you and Xtopay — it proves the request is genuinely from you.
Your Client Secret has the same power as a password. Never log it, never commit it to version control, never send it to a client browser or mobile app. Rotate it immediately if you suspect it has been compromised.
How Basic Auth works
HTTP Basic Auth encodes client_id:client_secret in Base64 and places it in the Authorization header:
const credentials = Buffer.from(
`${process.env.XTOPAY_CLIENT_ID}:${process.env.XTOPAY_CLIENT_SECRET}`
).toString("base64");
const response = await fetch("https://api.xtopay.co/v1/payments", {
method: "POST",
headers: {
"Authorization": `Basic ${credentials}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ ... }),
});If you use the official Xtopay SDK, the client handles this automatically:
import Xtopay from "@xtopay/node";
const xtopay = new Xtopay({
clientId: process.env.XTOPAY_CLIENT_ID!,
clientSecret: process.env.XTOPAY_CLIENT_SECRET!,
});Authentication errors
| HTTP status | Error code | Meaning |
|---|---|---|
401 | invalid_credentials | Client ID or Client Secret is wrong |
401 | credentials_missing | No Authorization header was sent |
403 | insufficient_scope | Your credentials don't have permission for this action |
403 | environment_mismatch | Test credentials used against a Live resource or vice versa |