Skip to main content
All API requests require authentication via an API key passed in the Authorization header.

​
API keys

API keys are scoped to an organization and created through the admin CLI or dashboard. Keys come in two modes:
ModePrefixBehavior
Testsk_test_Test payments, no real charges
Livesk_live_Real Visa cards, real payments
sk_test_abc123def456...   # test-mode key
sk_live_abc123def456...   # live-mode key
Production keys require an active subscription. Use agent-cards-admin env to switch between modes.

​
Base URL

There is one base URL for the API, in both test and live mode: 
https://api.agentcard.sh
The key prefix decides the mode — you do not switch URLs. A sk_test_ key issues test cards against https://api.agentcard.sh; a sk_live_ key issues real cards against the same URL. Nothing else in the request changes. Always send your requests to https://api.agentcard.sh, including for sk_test_ keys.

​
Making authenticated requests

Pass your API key as a Bearer token in the Authorization header: 
curl https://api.agentcard.sh/api/v1/cards \
  -H "Authorization: Bearer sk_test_abc123def456..."

​
Error responses

StatusErrorDescription
401Missing or invalid Authorization headerNo Authorization: Bearer header provided
401Invalid API key formatKey doesn’t start with sk_test_ or sk_live_
401Invalid or revoked API keyKey not found or revoked. Make sure you are calling https://api.agentcard.sh — see Base URL above.
403Organization is suspendedThe org associated with this key is suspended
429API key rate limit exceededPer-key rate limit exceeded (default: 1,000 req/hour)

​
Rate limits

Each API key has a configurable rate limit (default: 1,000 requests per hour). Rate limit headers are included in every response:
HeaderDescription
RateLimit-LimitMax requests allowed in the window
RateLimit-RemainingRequests remaining in the current window
RateLimit-ResetSeconds until the window resets

​
Key management

API keys can be managed through the agent-cards-admin CLI:
  • Create — Generate a new key for your organization
  • Set — Set the active API key for CLI commands
  • Rotate — Replace an existing key with a new one (old key keeps working for a 24-hour grace window, then is revoked)
  • Revoke — Permanently disable a key
  • List — View all keys for an organization