Skip to main content

API Keys

API keys let scripts, CI jobs, and provisioning tools call the ampersend Platform API on behalf of your user account.

API keys are used for user-level automation workflows such as:

  • Provisioning agents
  • Managing agent keys
  • Exporting transaction data
  • Managing allowlists and top-up settings

Key prefixes​

PrefixEnvironmentNotes
sk_live_Base MainnetIssued from https://app.ampersend.ai
sk_test_Base SepoliaIssued from https://app.sandbox.ampersend.ai

The prefix determines which deployment the key can access: a test key cannot call production and a production key cannot call sandbox.

Creating a key​

  1. Open the dashboard (production or sandbox).
  2. Go to API Keys in the user menu.
  3. Click Create API key, give it a name, and copy the secret.
caution

The secret is only shown once. Store it in a secret manager or .env file immediately; the dashboard only keeps a hashed copy.

What you can do with an API key​

API keys authenticate user-session routes. Common automation tasks:

  • Create an agent account: POST /agents
  • Add an agent key: POST /agents/{address}/keys
  • Manage agents, allowlists, and top-up settings
  • Export transaction history and payment events

For agent-scoped actions (such as managing the agent's own hosted endpoints), use the agent's session token instead. See Endpoint Commands.

Using a key​

Pass the key as a bearer token:

curl https://api.ampersend.ai/v1/agents \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json"

In scripts, read the key from an environment variable:

export AMPERSEND_API_KEY=sk_test_...

Rotation and revocation​

  • Rotate — create a new key, update consumers, then revoke the old key.
  • Revoke — click Revoke next to the key in the dashboard. Revocation is immediate; any call with the revoked key returns 401.

Rotate keys regularly and any time a key may have leaked (for example, committed to git, shared in chat). Because only the hash is stored, revocation is the recovery path, and the original secret cannot be recovered.

Security guidance​

  • Never commit API keys to version control. Use .env files (gitignored) or a secret manager.
  • Use sk_test_* keys for CI and local development; reserve sk_live_* for production automation.
  • Scope automation to the minimum set of agents and operations required.