Authentication

The Airclou API uses API keys to authenticate requests. You can view and manage your API keys in the Airclou Dashboard.

API key types

Airclou supports two types of API keys:

• Live keys — Used for production environments (prefix: ac_live_)
• Test keys — Used for development and testing (prefix: ac_test_)

Test keys allow you to experiment with the API without affecting your production data. They have the same capabilities as live keys but operate in a sandboxed environment.

Authentication method

Include your API key in the Authorization header of every request using the Bearer authentication scheme:

curl https://app.airclou.com/playbook/api/v1/users \
  -H "Authorization: Bearer ac_live_1234567890abcdef"

Creating API keys

To create a new API key:

1. Log in to your Airclou dashboard
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Choose the key type (live or test)
5. Provide a descriptive name
6. Optionally set an expiration date
7. Click Create

The key will be displayed once. Make sure to copy it immediately — you won’t be able to view it again.

Security best practices

Follow these security guidelines to keep your API keys safe:

Store securely

• Never commit API keys to version control
• Use environment variables or secret management services
• Rotate keys regularly (at least every 90 days)

# Good: Use environment variables
export AIRCLOU_API_KEY=ac_live_1234567890abcdef

# Bad: Hardcoding keys in your application
const apiKey = "ac_live_1234567890abcdef"; // Don't do this!

Limit key permissions

When creating an API key, assign only the permissions it needs:

• Read-only — For monitoring and analytics
• Read/Write — For standard operations
• Admin — For administrative tasks (use sparingly)

Monitor key usage

Regularly review your API key usage in the dashboard:

• Check for unusual activity patterns
• Monitor which keys are actively being used
• Revoke unused or compromised keys immediately

Use HTTPS only

Always make API requests over HTTPS. The Airclou API will reject any requests made over plain HTTP.

Revoking API keys

If an API key is compromised or no longer needed:

1. Navigate to Settings → API Keys
2. Find the key in the list
3. Click Revoke
4. Confirm the action

Revoked keys cannot be recovered. Any requests using a revoked key will fail with a 401 Unauthorized error.

Error responses

Authentication-related errors return the following status codes:

• 401 Unauthorized — Missing or invalid API key
• 403 Forbidden — Valid key but insufficient permissions

Example error response:

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided",
    "details": "The API key has been revoked or does not exist"
  }
}

Testing authentication

You can verify your API key is working correctly by calling the authentication test endpoint:

curl https://app.airclou.com/playbook/api/v1/auth/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response indicates your key is valid:

{
  "valid": true,
  "key_id": "key_1234567890",
  "permissions": ["read", "write"],
  "expires_at": "2025-12-31T23:59:59Z"
}