Skip to content

Authentication

All API requests (except the health check) require authentication via an API key.

Getting an API key

  1. Register for an Icana.AI account
  2. Log in to your dashboard
  3. Go to Settings → API Keys
  4. Click Create API Key and give it a name
  5. Copy the key immediately — it is only shown once

For more details on managing keys, see the API Keys dashboard guide.

Using your API key

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

curl https://api.icana.ai/api/v1/usage \
  -H "X-API-Key: sk_test_your_api_key_here"

Key format

API keys follow the format sk_test_ or sk_live_ followed by a random string:

sk_test_a1b2c3d4e5f6g7h8...
sk_live_a1b2c3d4e5f6g7h8...

Verifying your key

Test that your key is valid by calling the usage endpoint:

curl -s -o /dev/null -w "%{http_code}" \
  https://api.icana.ai/api/v1/usage \
  -H "X-API-Key: sk_test_your_api_key_here"
Response Meaning
200 Key is valid and active
401 Key is invalid, revoked, or missing

Security best practices

Keep your API key secret

Your API key grants access to your account and will incur charges for usage. Treat it like a password.

  • Never commit keys to version control. Use environment variables instead: 
    export ICANA_API_KEY="sk_test_your_api_key_here"
  • Never expose keys in client-side code. API calls should always be made from your server.
  • Rotate keys regularly. You can create up to 3 keys at a time, making it easy to rotate without downtime.
  • Revoke compromised keys immediately via the API Keys page in your dashboard.

Error responses

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "detail": "Invalid or missing API key"
}

See the Errors page for all error codes.