Skip to main content

​
Overview

API keys are the primary way to authenticate with ACN. Each key is tied to your developer account and shares the same balance and call history.

​
Creating a Key

​
From the Dashboard

  1. Go to app.acn.exchange
  2. Navigate to Settings → API Keys
  3. Click Create New Key
  4. Give it a descriptive name (e.g., “Production Agent”, “Dev Testing”)
  5. Copy the key immediately — it won’t be shown again

​
Via API

curl -X POST https://api.acn.exchange/v1/keys \
  -H "Authorization: Bearer acn_sk_existing_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Agent"}'

{
  "id": "key_abc123",
  "name": "My New Agent",
  "key": "acn_sk_lm3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b",
  "prefix": "acn_sk_lm3n",
  "created_at": "2026-03-08T12:00:00Z"
}
The full key is only shown once at creation time. Store it in a password manager or secrets vault immediately.

​
Key Format

acn_sk_<32 random characters>
The acn_sk_ prefix helps with:
  • Identifying ACN keys in logs
  • Secret scanning tools (GitHub, GitGuardian) can flag leaked keys
  • Quick visual identification

​
Rotating Keys

Best practice is to rotate keys periodically:
  1. Create a new key with a descriptive name
  2. Update your agent/application to use the new key
  3. Verify the new key works
  4. Revoke the old key
# Revoke the old key
curl -X DELETE https://api.acn.exchange/v1/keys/key_old_id \
  -H "Authorization: Bearer acn_sk_new_key"

​
Security Best Practices

Create different keys for development, staging, and production. This way, revoking a dev key doesn’t affect production.
# .env (gitignored)
ACN_API_KEY=acn_sk_your_key
Never hard-code keys in source code, configuration files, or commit them to version control.
For production deployments, use AWS Secrets Manager, Google Secret Manager, Azure Key Vault, or similar. Inject keys at runtime, not build time.
Check the last_used_at field on your keys. If a key hasn’t been used in a while, consider revoking it.
If a key is accidentally exposed:
  1. Revoke it immediately from the dashboard
  2. Create a new key
  3. Update all services using the old key
  4. Review call history for unauthorized usage

​
Listing Keys

curl https://api.acn.exchange/v1/keys \
  -H "Authorization: Bearer acn_sk_your_key"
Returns all keys with their prefix and last usage time (never the full key value).

​
Spending Limits per Key

You can set per-key spending limits to control how much a specific API key is allowed to spend. This is useful when you have multiple keys (e.g., one per agent or per environment) and want budget isolation between them.
Per-key limits are checked in addition to account-level limits. A key is blocked if either the key-level or account-level limit is exceeded.

​
Set Limits on a Key

curl -X PUT https://api.acn.exchange/v1/keys/key_abc123 \
  -H "Authorization: Bearer acn_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dailySpendLimitUsdc": "10.00",
    "perCallLimitUsdc": "0.05"
  }'
FieldDescription
dailySpendLimitUsdcMax credits this key can spend per UTC day. null = no limit.
perCallLimitUsdcMax credits this key can spend on a single call. null = no limit.
When a key-level limit is exceeded, the call returns HTTP 402 with code ACN-CREDIT-002.
KeyPurposeSuggested Limit
production-agentLive trafficAccount-level limit only
dev-testingLocal development5/day+5/day + 0.02/call cap
ci-pipelineAutomated tests$1/day
This prevents a runaway test suite or development loop from consuming your production balance.