API Authentication

All requests to the Tula API must be authenticated using an API key. API keys are long-lived credentials tied to a specific user account and permission scope. This guide covers how to generate, use, manage, and rotate API keys.

Generating an API Key

API keys are created through the Tula web interface:

1. Log in to the Tula web interface with an account that has admin or superadmin privileges.
2. Navigate to System > API Keys.
3. Click Create API Key.
4. Enter a descriptive name for the key that identifies its intended use (e.g., "CI/CD Pipeline", "Monitoring Integration", "Terraform Automation").
5. Select the permission scope for the key (see Key Permissions below).
6. Click Generate. The full API key will be displayed once. Copy it immediately and store it in a secure location such as a secrets manager or encrypted vault. The key cannot be retrieved again after this screen is dismissed.

Using the API Key

Include the API key in every API request using one of the following methods.

Authorization Header (Recommended)

Pass the key in the Authorization header using the Bearer scheme:

curl -X GET https://<appliance-ip>/api/v1/vips \
  -H "Authorization: Bearer tula_ak_7f3b9c2e1d4a8f6b0e5c7d9a3f1b8e4c" \
  -H "Content-Type: application/json"

Query Parameter

Alternatively, pass the key as a query parameter. This method is less secure because the key may appear in server logs and browser history. Use it only when headers are not supported by your client:

curl -X GET "https://<appliance-ip>/api/v1/vips?api_key=tula_ak_7f3b9c2e1d4a8f6b0e5c7d9a3f1b8e4c"

Key Permissions

Each API key is assigned a permission scope that controls which operations it can perform:

API keys inherit the role-based access controls of the user account that created them. A key created by an observer account is limited to read-only operations regardless of the selected scope. Keys created by admin accounts can be scoped up to Read/Write. Only superadmin accounts can create Full Access keys.

Key Rotation

Regular key rotation reduces the risk associated with credential exposure. To rotate an API key:

1. Navigate to System > API Keys in the web interface.
2. Click Create API Key to generate a new key with the same name and scope as the one being replaced.
3. Update all systems and scripts that use the old key to reference the new key.
4. Verify that all integrations are functioning correctly with the new key.
5. Delete the old key by clicking the Revoke button next to it in the API key list.

There is no automatic key expiration by default. You can optionally set an expiration date when creating a key. Expired keys are automatically disabled and return a 401 Unauthorized response.

Example Requests

List All VIPs

curl -X GET https://<appliance-ip>/api/v1/vips \
  -H "Authorization: Bearer tula_ak_7f3b9c2e1d4a8f6b0e5c7d9a3f1b8e4c" \
  -H "Content-Type: application/json"

Create a Backend Server

curl -X POST https://<appliance-ip>/api/v1/vips/1/backends \
  -H "Authorization: Bearer tula_ak_7f3b9c2e1d4a8f6b0e5c7d9a3f1b8e4c" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-03",
    "ip_address": "10.0.1.13",
    "port": 8080,
    "weight": 100
  }'

Check Appliance Status

curl -X GET https://<appliance-ip>/api/v1/status \
  -H "Authorization: Bearer tula_ak_7f3b9c2e1d4a8f6b0e5c7d9a3f1b8e4c"

Security Best Practices

• Store API keys in a secrets manager or environment variables, never in source code or configuration files committed to version control.
• Use the most restrictive permission scope that satisfies the integration's requirements.
• Create separate keys for each integration or automation workflow so that revoking one key does not disrupt unrelated systems.
• Monitor API key usage through the Tula audit log under System > Logs to detect unauthorized or anomalous access patterns.
• Rotate keys on a regular schedule and immediately after any suspected compromise.