Authentication

The Payments for AI Agents API uses Bearer token authentication. Every request must include an Authorization header containing the token from the agent instructions for a Holyheld card.

This is not the same as X-Api-Key

The APIs use X-Api-Key for partner authentication. The Payments for AI Agents API uses a separate Bearer token tied to a single user's Holyheld card. The two keys are obtained differently, work at different endpoints, and cannot be used interchangeably.

Authentication header

Include this header in every request:

Authorization: Bearer <your-token>

Example:

Authorization: Bearer hh_agent_a1b2c3d4e5f6...

How to obtain agent instructions

The user does not create standalone agent tokens. The user creates a Holyheld card, then copies the agent instructions for that card. Those instructions include the Bearer token required for API access.

1. Log in to your Holyheld account.
2. Create a card in the app.
3. After the card is created, click the button to copy the link to the agent instructions. The instructions include the agent token required for API access.

If the card has already been created, you can retrieve the instructions again at any time.

Complete request example

curl

curl https://apicore.holyheld.com/v4/ai-agents/balance \
  -H "Authorization: Bearer $HOLYHELD_AGENT_TOKEN"

JavaScript

const response = await fetch(
  'https://apicore.holyheld.com/v4/ai-agents/balance',
  {
    headers: {
      Authorization: `Bearer ${process.env.HOLYHELD_AGENT_TOKEN}`,
    },
  }
);
const data = await response.json();

Python

import httpx, os

response = httpx.get(
    'https://apicore.holyheld.com/v4/ai-agents/balance',
    headers={'Authorization': f"Bearer {os.environ['HOLYHELD_AGENT_TOKEN']}"},
)
data = response.json()

Security best practices

Store the token as an environment variable. Never hardcode it in source files, commit it to version control, or include it in client-side code.

# In your shell profile or .env file
HOLYHELD_AGENT_TOKEN=hh_agent_a1b2c3...

Keep the server local when using MCP. If you are running an MCP server that wraps this API, keep it running locally on the user's machine. The Bearer token never leaves the local environment.

Replace the agent instructions on compromise. If you suspect the token from an agent instruction has been exposed, get a new agent instruction for the card and update the agent configuration immediately. There is no grace period — an exposed token gives access to the card balance, card details, and top-up capability up to the configured spending limit.

Use one card per agent when isolation matters. Because the agent token is tied to a card, create separate cards for separate agents or integrations when you want independent spending limits and replacement paths.

Spending limits

Each agent-enabled card can be configured with a cumulative spending limit — the maximum total EUR amount the agent is allowed to top up across all requests. This limit is set in the Holyheld dashboard for the card's agent access.

When the limit is reached, any further top-up request returns AI_TOPUP_LIMIT_EXCEEDED. The agent cannot reset this limit — only the user can, from the dashboard.

See Error Reference for handling this and other authentication errors.

Authentication errors

HTTP status	Error code	Cause	Fix
401	AI_AUTHORIZATION_INVALID	Authorization header missing entirely	Add the Authorization: Bearer <token> header
403	AI_AUTHORIZATION_INVALID	Token is invalid, revoked, or agent access is disabled	Check the token value; get a new agent instruction for the card if needed

Both responses follow the standard error shape:

{
  "status": "error",
  "errorCode": "AI_AUTHORIZATION_INVALID",
  "error": "Authorization header missing"
}

Next steps

With authentication configured, make your first request: Get Balance.