Authentication

Authenticate with a secret key, scope it per resource, and keep it safe.

Send your secret key as a bearer token in the Authorization header. A key belongs to one business, and every request made with it acts as that business. The same key works on both of the API's base URLs.

Authenticated request

curl "https://api.402pay.co/api/v1/payments?limit=1" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY"

const response = await fetch("https://api.402pay.co/api/v1/payments?limit=1", {
  headers: {
    Authorization: `Bearer ${process.env.PAY402_SECRET_KEY}`,
  },
});
const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://api.402pay.co/api/v1/payments?limit=1",
    headers={
        "Authorization": f"Bearer {os.environ['PAY402_SECRET_KEY']}",
    },
)
data = response.json()["data"]

Key types

Prefix	Kind	Use
`402s_live_`	Secret	Server-side requests. Every payment it creates is real.
`402p_…`	Publishable	Reserved for browser-side use later. Nothing accepts it today: an endpoint that needs a key answers it with 401 `invalid_api_key`, so you can ignore it for now.

Keep secret keys on your server and out of source control. Only a hash is stored, so a lost secret can't be shown again: create a new key, then revoke the old one.

In the dashboard: Create and manage API keys.

Restricted keys

A secret key has full access, or a level per resource: none, read or write. GET requests need read and every other method needs write, so a key that only reports on payments can't create one.

Resource	Covers
Payments	Payments and metrics.
Links	Payment links.
Customers	Customer records.
Wallet	Balances, addresses and notes.
Webhooks	Endpoints, deliveries and test events.
Events	The event log. Read only.
Checkout settings	Accepted coins, rails and redirects.

Money never moves on an API key. Sends from your wallet happen in the dashboard, signed in your browser with your encryption password.

Errors

Status	Code	When
401	`unauthenticated`	No key was sent. The response has a `WWW-Authenticate: Bearer` header.
401	`invalid_api_key`	The key is invalid or revoked, or it's a publishable key.
401	`invalid_api_key`	The `Authorization` header isn't `Bearer`, a space and the key, such as when the `Bearer` prefix is missing.
403	`business_forbidden`	The request also sent a `402pay-Business` header naming another business. A key acts only as its own business, so leave the header out.
403	`permission_denied`	A restricted key doesn't have the access the route needs.
403	`session_required`	The route is for the dashboard only, such as managing API keys or sending from your wallet.