Skip to main content

​
What are API Keys?

API keys in ActumX are used to authenticate requests to protected endpoints, including:
  • x402 paid endpoints
  • MCP (Model Context Protocol) tools
  • Protected resources and agent operations
Each API key is scoped to your user account and can be revoked independently.

​
API Key Format

ActumX API keys follow this format: 
xk_live_[48 hexadecimal characters]
Example: xk_live_a1b2c3d4e5f6...
The key generation uses cryptographically secure random bytes. See api/src/lib/crypto.ts:15-17.

​
Creating API Keys

1

Create a New API Key

Make a POST request to generate a new API key:
curl -X POST http://localhost:3001/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -d '{
    "name": "Production Agent Key"
  }'
Response:
{
  "apiKeyId": "key_x1y2z3a4b5c6",
  "apiKey": "xk_live_a1b2c3d4e5f6789...",
  "keyPrefix": "xk_live_a1b2c3",
  "warning": "Store this key now. It is shown only once."
}
Critical: Save the apiKey value immediately! It cannot be retrieved after creation.
2

Store the API Key Securely

Store your API key in a secure location:Environment Variable:
export ACTUMX_API_KEY="xk_live_a1b2c3d4e5f6789..."
Configuration File (.env):
.env
ACTUMX_API_KEY=xk_live_a1b2c3d4e5f6789...
Never commit API keys to version control. Add .env to your .gitignore.

​
Using API Keys

​
Bearer Token Authentication

Include your API key in the Authorization header: 
curl http://localhost:3001/v1/protected/quote \
  -H "Authorization: Bearer xk_live_a1b2c3d4e5f6789..."

​
MCP Tool Authentication

For MCP (Model Context Protocol) endpoints, use the same Bearer token: 
curl -X POST http://localhost:3001/mcp \
  -H "Authorization: Bearer xk_live_a1b2c3d4e5f6789..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

​
Listing API Keys

View all your API keys (active and revoked): 
curl http://localhost:3001/v1/api-keys \
  -H "Cookie: YOUR_SESSION_COOKIE"
Response: 
{
  "keys": [
    {
      "id": "key_x1y2z3a4b5c6",
      "name": "Production Agent Key",
      "keyPrefix": "xk_live_a1b2c3",
      "revokedAt": null,
      "lastUsedAt": "2026-03-03T23:45:00.000Z",
      "createdAt": "2026-03-03T22:30:00.000Z"
    },
    {
      "id": "key_abc123def456",
      "name": "Old Development Key",
      "keyPrefix": "xk_live_def456",
      "revokedAt": "2026-03-02T10:00:00.000Z",
      "lastUsedAt": "2026-03-01T15:30:00.000Z",
      "createdAt": "2026-02-15T09:00:00.000Z"
    }
  ]
}
Only the key prefix is shown in the list. The full key is never retrievable after creation.

​
Revoking API Keys

Revoke a key to immediately prevent it from authenticating requests: 
curl -X DELETE http://localhost:3001/v1/api-keys/key_x1y2z3a4b5c6 \
  -H "Cookie: YOUR_SESSION_COOKIE"
Revocation is immediate. Any requests using the revoked key will fail with a 401 error.

​
Key Implementation Details

​
How API Keys are Stored

From api/src/modules/api-keys/service.ts:39-53:
  1. Generate a random API key using newApiKey()
  2. Extract the first 14 characters as the keyPrefix (for display)
  3. Hash the full key using SHA-256
  4. Store only the hash in the database (never the plain key)
  5. Return the plain key to the user (only once)
const rawKey = newApiKey();
const keyPrefix = rawKey.slice(0, 14);
const keyHash = hashSecret(rawKey);

​
Authentication Flow

When you make an authenticated request:
  1. Extract the API key from the Authorization header
  2. Hash the provided key
  3. Look up the key by its hash in the database
  4. Verify it’s not revoked (revokedAt is null)
  5. Update lastUsedAt timestamp
  6. Proceed with the request

​
Security Best Practices

Rotate Keys Regularly

Create new keys and revoke old ones periodically to minimize exposure

Use Descriptive Names

Name keys by purpose (e.g., “Production API”, “CI/CD Pipeline”) for easy identification

Revoke Unused Keys

Immediately revoke keys that are no longer needed or may be compromised

Monitor Usage

Check lastUsedAt timestamps to identify inactive or suspicious keys

​
Troubleshooting

Possible Causes:
  • API key is missing from the request
  • API key format is incorrect
  • API key has been revoked
  • API key was never created successfully
Solutions:
  • Verify the Authorization header format: Bearer xk_live_...
  • List your API keys to check if the key exists and is not revoked
  • Create a new API key if needed
Check:
  • Ensure you copied the entire key (including xk_live_ prefix)
  • Verify there are no extra spaces or line breaks
  • Confirm you’re using the latest key (not an old one)
API keys cannot be retrieved after creation for security reasons.Solution:
  1. Revoke the lost key
  2. Create a new key
  3. Update your application configuration

​
Next Steps

Top Up Credits

Add credits to your account for using paid endpoints

Make Paid Requests

Learn how to use x402 payment protocol