Skip to main content
The Avala API uses API keys for authentication. Include your key in the X-Avala-Api-Key header with every request. All requests must be made over HTTPS.

​
Creating an Account

If you don’t have an account yet, use the signup endpoint. This is the only endpoint that does not require authentication. 
curl -X POST https://api.avala.ai/api/v1/signup/ \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@acme.com", "password": "SecurePass123!"}'
The response includes your user details and an API key: 
{
  "user": {
    "uid": "abc123",
    "username": "dev@acme.com",
    "email": "dev@acme.com",
    "first_name": "",
    "last_name": ""
  },
  "api_key": "avk_..."
}
The signup endpoint is rate-limited to 5 requests per minute per IP address.

​
Creating API Keys

  1. Log in to Mission Control.
  2. Navigate to Settings → Security.
  3. Click Create API Key.
  4. Give the key a descriptive name (e.g., production-backend, ci-pipeline).
  5. Copy the key immediately.
API keys are only displayed once at creation time. Store your key in a secure location before closing the dialog — you will not be able to view it again.

​
Using API Keys

Pass your API key in the X-Avala-Api-Key header: 
curl https://api.avala.ai/api/v1/agents \
  -H "X-Avala-Api-Key: avk_your_api_key"

​
API Key Scopes

When creating an API key, you can restrict it to specific capabilities using scopes. A key with no scopes selected has full organization-level access, so avoid using broad keys for machine automation such as MCP unless you explicitly need it.
ScopePermission
datasets.readList and retrieve datasets and dataset items.
datasets.writeCreate, update, and delete datasets. Upload items.
projects.readList and retrieve projects, tasks, and task results.
exports.createCreate new exports and download completed exports.
tasks.readList and retrieve tasks and their results.
Use the principle of least privilege: give each key only the scopes it needs. For example, a CI pipeline that only downloads exports should use a key with exports.create scope only.

​
Managing API Keys

You can manage your API keys from Settings → Security in Mission Control:
  • View active keys — See all keys, their names, scopes, and creation dates.
  • Revoke a key — Immediately invalidate a key. Revoked keys cannot be restored.
  • Regenerate a key — Create a new key to replace an existing one.

​
Key Expiration

API keys do not expire by default. If your organization enforces key expiration policies, expired keys return a 401 error. Regenerate the key from Mission Control to restore access.

​
Best Practices

Follow these guidelines to keep your API keys secure.
  • Use environment variables — Never hard-code API keys in source code. Load them from environment variables or a secrets manager. 
    export AVALA_API_KEY="avk_your_api_key"
  • Rotate keys regularly — Revoke and regenerate keys on a recurring schedule, especially after team changes.
  • Use separate keys per environment — Create distinct keys for development, staging, and production so you can revoke one without affecting others.
  • Restrict access — Only share keys with the people and services that need them. Audit key usage periodically.

​
Error Responses

The API returns the following errors for authentication failures: Invalid API Key (401) 
{
  "detail": "Invalid API key."
}
Expired API Key (401) 
{
  "detail": "API key has expired."
}
Missing API Key (401) 
{
  "detail": "Authentication credentials were not provided."
}

​
Next Steps

API Overview

Base URL, rate limits, pagination, and response format.

Error Codes

Full reference for every error code the API can return.