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

# Authentication

> How to authenticate with the Avero Public API using API keys.

## Overview

The Avero Public API uses **Bearer token** authentication. Every request must include an `Authorization` header with a valid API key.

```
Authorization: Bearer pf_live_xxxxxxxxxxxxxxxxxxxx
```

API keys begin with `pf_live_` followed by a 43-character URL-safe random string.

## Creating an API key

1. Open the Avero desktop app and go to **Settings → Developers**.
2. Click **Create API key**, enter a name, and select the scopes you need.
3. Copy the key — it is shown **only once**. Store it securely (e.g. in an environment variable or secrets manager).

<Warning>
  Never embed an API key in client-side code or commit it to version control.
</Warning>

## Scopes

Each key has one or more scopes that limit what it can do.

| Scope | What it allows |
| - | - |
| `leads:write` | Create and upsert leads via `POST /v1/leads` |
| `calls:read` | List calls via `GET /v1/calls` |
| `recordings:read` | Fetch signed recording URLs via `GET /v1/calls/{id}/recording` |

A request using a key that lacks the required scope returns `403 Forbidden`.

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.averohq.sk/v1/calls \
    -H "Authorization: Bearer pf_live_YOUR_KEY_HERE"
  ```

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

  client = httpx.Client(base_url="https://api.averohq.sk")
  response = client.get(
      "/v1/calls",
      headers={"Authorization": "Bearer pf_live_YOUR_KEY_HERE"},
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.averohq.sk/v1/calls", {
    headers: {
      Authorization: "Bearer pf_live_YOUR_KEY_HERE",
    },
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Rate limits

The API is rate-limited to **60 requests per minute** per API key. Exceeding the limit returns `429 Too Many Requests`. The response includes a `Retry-After` header indicating how many seconds to wait.

## Error responses

| HTTP status | Meaning |
| - | - |
| `401 Unauthorized` | Missing or invalid API key |
| `403 Forbidden` | Key does not have the required scope |
| `422 Unprocessable Entity` | Invalid request body (see `detail` field) |
| `429 Too Many Requests` | Rate limit exceeded |
| `503 Service Unavailable` | Temporary server issue — retry with backoff |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.