> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate with the Avala API using API keys passed in the X-Avala-Api-Key header.

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.

```bash theme={null}
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:

```json theme={null}
{
  "user": {
    "uid": "abc123",
    "username": "dev@acme.com",
    "email": "dev@acme.com",
    "first_name": "",
    "last_name": ""
  },
  "api_key": "avk_..."
}
```

<Info>
  The signup endpoint is rate-limited to 5 requests per minute per IP address.
</Info>

## Creating API Keys

1. Log in to [Mission Control](https://avala.ai).
2. Navigate to **[Settings → Security](https://avala.ai/settings?section=security)**.
3. Click **Create API Key**.
4. Give the key a descriptive name (e.g., `production-backend`, `ci-pipeline`).
5. Copy the key immediately.

<iframe width="560" height="315" src="https://www.youtube.com/embed/TYdLhkAAbLA" title="Generate API Keys" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

<Warning>
  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.
</Warning>

## Using API Keys

Pass your API key in the `X-Avala-Api-Key` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.avala.ai/api/v1/agents \
    -H "X-Avala-Api-Key: avk_your_api_key"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.avala.ai/api/v1/agents",
      headers={"X-Avala-Api-Key": "avk_your_api_key"},
  )

  data = response.json()
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.avala.ai/api/v1/agents", {
    headers: {
      "X-Avala-Api-Key": "avk_your_api_key",
    },
  });

  const data = await response.json();
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/agents", nil)
  	req.Header.Set("X-Avala-Api-Key", "avk_your_api_key")

  	client := &http.Client{}
  	resp, err := client.Do(req)
  	if err != nil {
  		panic(err)
  	}
  	defer resp.Body.Close()

  	body, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(body))
  }
  ```
</CodeGroup>

## 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.

| Scope               | Permission                                                                           |
| ------------------- | ------------------------------------------------------------------------------------ |
| `datasets.read`     | List and retrieve datasets and dataset items.                                        |
| `datasets.write`    | Create, update, and delete datasets. Upload items.                                   |
| `projects.read`     | List and retrieve projects, tasks, and task results.                                 |
| `projects.write`    | Approve, pause, resume, cancel, and archive projects. Clone projects from templates. |
| `exports.create`    | Create new exports and download completed exports.                                   |
| `tasks.read`        | List and retrieve tasks and their results.                                           |
| `storage.read`      | List storage configurations.                                                         |
| `storage.write`     | Create and test storage configurations.                                              |
| `work_batches.read` | List and retrieve work batch status and progress.                                    |

<Tip>
  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.
</Tip>

## Managing API Keys

You can manage your API keys from **[Settings → Security](https://avala.ai/settings?section=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

<Tip>
  Follow these guidelines to keep your API keys secure.
</Tip>

* **Use environment variables** — Never hard-code API keys in source code. Load them from environment variables or a secrets manager.

  ```bash theme={null}
  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)**

```json theme={null}
{
  "detail": "Invalid API key."
}
```

**Expired API Key (401)**

```json theme={null}
{
  "detail": "API key has expired."
}
```

**Missing API Key (401)**

```json theme={null}
{
  "detail": "Authentication credentials were not provided."
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="" icon="book" href="/docs/api-reference/overview">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>API Overview</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Base URL, rate limits, pagination, and response format.</p>
  </Card>

  <Card title="" icon="circle-exclamation" href="/docs/api-reference/errors">
    <p style={{fontWeight: 600, fontSize: '18px', marginBottom: '4px', marginTop: '8px', color: 'inherit'}}>Error Codes</p>
    <p style={{fontSize: '14px', marginTop: '0px', opacity: 0.6}}>Full reference for every error code the API can return.</p>
  </Card>
</CardGroup>