Agent Authentication

This page covers everything an agent needs to handle credentials correctly: which header to send, how keys route between environments, how to rotate without downtime, and how to respond to auth errors.

Use When#

Use this page when an agent is storing, rotating, or debugging credentials, or when implementing its request layer against the Balance API.

Inputs#

• A Balance API key for the right environment. pk_test_* for Sandbox, pk_live_* for Production.
• A secret store the agent can read at runtime and the human operator can update.
• A plan for how the agent will surface 401, 403, and 429 responses.

The Header#

The Balance API authenticates every request with the X-Api-Key header:

POST /api/v1/balance/delta HTTP/1.1
Host: balance-api.pacspace.io
X-Api-Key: pk_live_PUBLIC.SECRET
Content-Type: application/json

The SDK does this automatically when an agent passes apiKey into the client.

Environment Routing#

The key prefix controls where traffic lands. An agent must never mix prefixes across environments.

Sandbox and Production run on dedicated, isolated infrastructure. A pk_test_* key never reaches Production data, and a pk_live_* key never reaches Sandbox data.

The SDK selects the endpoint from the prefix automatically, so in most cases the agent only needs to pass the correct key and the routing is handled transparently. Endpoint overrides exist in the SDK constructor but are not needed for standard deployments.

Key Format#

pk_{environment}_{publicId}.{secret}

The public identifier and the secret are separated by a period. Both halves must stay together. An agent should store the full string as an opaque credential and never attempt to split, truncate, or log the secret portion.

Agent Credential Storage#

Agents usually load credentials from a secret manager or environment variable. Three rules cover every safe setup:

1. Read the key from a server-side secret, not from client-side code, prompts, or user input.
2. Scope one key per service, environment, or responsibility, so any single revocation has a bounded blast radius.
3. Never log the full key, never serialize it into telemetry, and never let it end up in a proof or receipt payload shared with a counterparty.

Rotating Keys#

Rotation should be a non-event for a running agent. The recommended procedure:

1. Create a new key in the same environment in the dashboard.
2. Deploy the new key to the agent's secret store alongside the existing key.
3. Cut the agent over to the new key in a single configuration change.
4. Confirm traffic and webhooks continue to flow on the new key.
5. Revoke the old key.

The dashboard keeps both keys active during the transition, so there is no downtime window and no need for the agent to support simultaneous failover between two keys.

Auth Error Handling#

The Balance API returns structured auth errors the agent should handle distinctly:

401 and 403 are permanent errors until a human acts. Retrying will only multiply failures. 429 is transient and should be retried with bounded exponential backoff.

Webhook Authentication#

Webhook deliveries are authenticated separately, with a webhook signing secret rather than the Balance API key. An agent that consumes webhooks should:

• Store the webhook signing secret in the same secret store as the API key, under a distinct name.
• Verify both the X-PacSpace-Signature and the X-PacSpace-Timestamp on every delivery.
• Reject deliveries with a timestamp older than five minutes.

Full signature verification procedure lives on Signature Verification.

Public Verification#

Public verification requires no key. GET /api/v1/verify/:proofRoot is intentionally open so that any counterparty, auditor, or downstream agent can confirm a proof without needing PacSpace credentials. This is how a receipt becomes useful outside the agent's own perimeter.

Idempotency#

Idempotency does not depend on authentication, but the agent should never reuse an idempotency key across keys in different environments. Key the idempotency header to both the business reference and, if relevant, the environment so a single retry never crosses environments.

Retry#

Bounded exponential backoff on transient errors only: 408, 429, 5xx. Never retry 401, 403, or 4xx validation errors; fix the inputs first.

Failure Modes#

• Using a pk_test_* key against a Production endpoint or a pk_live_* key against a Sandbox endpoint — requests will fail authentication.
• Storing the API key in a client-side bundle or browser-visible configuration.
• Logging the full key into telemetry, stdout, or error dumps.
• Retrying 401 and 403 responses, which only compounds the failure without fixing it.
• Rotating a key without deploying the replacement first, which causes downtime.

Related Pages#

• Authentication — full Balance API authentication reference.
• API Key Management — creating and revoking keys.
• Safety and Idempotency — retries and idempotency keys.
• Capabilities — the operations an authenticated agent can call.