Authentication

Every request carries your secret API key as a bearer token. Keys are created in the console, shown once, and can expire.

API keys

Create and manage keys in the AgentPay console under Developer, API keys. A key looks like mk_live_... and is shown only once, at creation. AgentPay stores a hash of it, so a lost key cannot be recovered: revoke it and create a new one.

A key can be given an expiry date when it is created. A key created without one never expires.

Sending the key

Send the key as a bearer token in the Authorization header of every request.

cURL

export AGENTPAY_API_KEY="mk_live_your_key_here"

curl https://api.joomjoo.com/v1/wallet \
  -H "Authorization: Bearer $AGENTPAY_API_KEY"

The SDKs take the key once, at construction, and send it on every call.

import { AgentPay } from "@agentpay-global/sdk";
const agentpay = new AgentPay(process.env.AGENTPAY_API_KEY);

import os
from agentpay import AgentPay
agentpay = AgentPay(api_key=os.environ["AGENTPAY_API_KEY"])

Keep the key server-side. Never ship it in a browser, a mobile app, an agent prompt, a log line or a repository. The key is the account: whoever holds it can issue cards against your wallet.

Authentication errors

Status	Code	Meaning
401	`missing_api_key`	No `Authorization: Bearer` header on the request.
401	`invalid_api_key`	The key is unknown or has been revoked.
401	`expired_api_key`	The key passed its expiry. The body carries `expired_at` and the message says when. Create a new key in the console and replace it.

401

{
  "error": "expired_api_key",
  "message": "This key expired on 2026-11-01T03:00:00.000Z. Create a new key in the console, then replace it here.",
  "expired_at": "2026-11-01T03:00:00.000Z",
  "request_id": "req_a1b2c3"
}

Request ids

Every response carries an X-Mooj-Request-Id header, echoed as request_id in the body. Quote it when you contact support about a call; it finds the exact request in the log.

One key, one account

A key resolves to exactly one account. Everything the key does, cards, checkouts, connections, top-ups, happens on that account and shows up in the console's Activity. Lookups never reveal whether an id belongs to another account: a card or checkout you do not own answers 404, the same as one that does not exist.