API Keys

API keys are the primary way to authenticate with the AgentPay API. Every request that creates or lists wallets, makes a payment, or fetches spend history must include a valid key in the X-Api-Key header. Key creation is the only operation that does not require authentication—you create a key once and then use it for all subsequent calls.

Creating an API key

Send POST /api-keys with an optional label and, if you want to supply your own secret, a key value. If key is omitted or empty, the API generates a new key with the prefix pk_. The plaintext key is returned only in this response; store it securely (e.g. in an environment variable or secrets manager).

POST /api-keys
Content-Type: application/json

{ "label": "my-agent" }
# Or with a custom key: { "key": "pk_my_custom_value", "label": "..." }

# Response 201
{
  "id": "uuid",
  "label": "my-agent",
  "key": "pk_..."
}
# Store "key"; it is only returned once.

Using the key

Include the key in the X-Api-Key header for all authenticated endpoints:

X-Api-Key: pk_...

The SDKs accept the key in their configuration and attach this header automatically. Never log or expose the key in client-side code or public repositories.

Dashboard keys and linking

When you sign in to the AgentPay dashboard with GitHub, the system creates or links API keys for your organization. Keys are stored encrypted and shown on the API Keys page. If you created keys outside the dashboard (e.g. via POST /api-keys or using the AgentPay skill in an AI coding agent), those keys are "unclaimed" until you link them: on the API Keys page, click Link existing key and paste your key. The key then appears in your list and counts toward your plan's key limit; see Plans and limits for unclaimed vs. claimed behavior and limits.

Rotating a key is done by creating a new key (via the API or dashboard) and updating your configuration; there is no in-place revocation endpoint.

Security

Treat API keys as secrets. Use different keys for development, staging, and production so a compromise is limited in scope. See Security best practices for more guidance.