Setting up API keys

API keys let external systems (your CRM, website, apps) communicate with AIsoule programmatically.

Creating an API key

1. Go to Settings → API Keys
2. Click "New API Key"
3. Configure:
   • Name — Descriptive name (e.g., "CRM Integration", "Website Widget")
   • Expiry — When the key expires (optional, recommended for security)
4. Click Create
5. Copy the key immediately — it's only shown once!

Using the API key

Include the key in the X-API-Key header of every request:

curl -H "X-API-Key: ak_live_xxxxxxxxxxxx" \
  https://app.aisoule.com/api/contacts

Managing keys

Viewing active keys

Go to Settings → API Keys to see all keys with:

• Name
• Created date
• Last used date
• Expiry date
• Status (active/expired/revoked)

Revoking a key

If a key is compromised or no longer needed:

1. Find the key in the list
2. Click "Revoke"
3. The key stops working immediately

Rotating keys

Best practice — rotate keys every 90 days:

1. Create a new key
2. Update your integration to use the new key
3. Verify it works
4. Revoke the old key

Security best practices

1. Never share keys publicly — Don't put them in frontend code, GitHub, or emails
2. Use environment variables — Store keys in .env files, not source code
3. Set expiry dates — Keys without expiry are a security risk
4. One key per integration — If one is compromised, only that integration is affected
5. Monitor usage — Check "Last used" to detect unauthorized access
6. Revoke unused keys — If an integration is decommissioned, revoke its key

Rate limits

API keys are subject to rate limiting:

• 100 requests per minute per key
• 10 requests per second burst
• Exceeding limits returns HTTP 429 (Too Many Requests)

Permissions

API keys inherit the permissions of the user who created them. If you need restricted access, create a user with a limited role and generate the key from that account.