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

# Authentication

> Create an API key and authenticate your SDK and API requests.

AgentVista uses API keys for SDK and programmatic access. The dashboard uses session-based authentication handled automatically when you log in.

## API keys

API keys authenticate requests to ingestion and dashboard API endpoints. Every key:

* Starts with a short prefix (e.g. `av_a1b2c3d4`)
* Has one or more **scopes** that control what it can do
* Is shown in full **once** at creation — store it immediately

### Scopes

| Scope   | Purpose                                                              |
| ------- | -------------------------------------------------------------------- |
| `write` | Required for all ingestion endpoints (`/traces/batch`, `/otlp/v1/*`) |
| `read`  | Required for dashboard read endpoints and the ping endpoint          |

The SDK only needs `write` scope to send traces.

### Create an API key

<Steps>
  <Step title="Open API Keys settings">
    In the dashboard, go to **Settings → API Keys**.
  </Step>

  <Step title="Create a key">
    Click **Create Key**, enter a name (e.g., `production`), select the `write` scope, and confirm.
  </Step>

  <Step title="Copy the key">
    The full key is displayed once. Copy it now.

    <Warning>
      You cannot retrieve the full key after closing this dialog. If you lose it, revoke the key and create a new one.
    </Warning>
  </Step>
</Steps>

### Use the key in the SDK

Pass your key to `agentvista.init()`:

```python theme={null}
import agentvista

agentvista.init(api_key="av_a1b2c3d4...")
```

<Tip>
  Store the key in an environment variable rather than hardcoding it:

  ```python theme={null}
  import os, agentvista
  agentvista.init(api_key=os.environ["AGENTVISTA_API_KEY"])
  ```
</Tip>

### Use the key in HTTP requests

Pass the key as a Bearer token in the `Authorization` header:

```bash theme={null}
curl https://api.agentvista.dev/api/v1/me/api-keys/ping/ \
  -H "Authorization: Bearer av_a1b2c3d4..."
```

A successful response returns `{"status": "ok"}`.

### Verify a key

Use the ping endpoint to confirm a key is valid and has the expected scopes:

```bash theme={null}
curl https://api.agentvista.dev/api/v1/me/api-keys/ping/ \
  -H "Authorization: Bearer av_a1b2c3d4..."
```

```json theme={null}
{"status": "ok"}
```

### Revoke a key

Go to **Settings → API Keys**, find the key by its prefix, and click **Revoke**. Revoked keys immediately stop authenticating requests.

You can also revoke via the API:

```bash theme={null}
curl -X DELETE https://api.agentvista.dev/api/v1/me/api-keys/{key_id}/ \
  -H "Authorization: Bearer av_a1b2c3d4..."
```

## Error responses

| Status                  | Meaning                                    |
| ----------------------- | ------------------------------------------ |
| `401 Unauthorized`      | Missing or invalid API key                 |
| `403 Forbidden`         | Key is valid but lacks the required scope  |
| `429 Too Many Requests` | Monthly event limit exceeded for your plan |

When you receive a `429`, check your usage in **Settings → Billing** and consider upgrading your plan or enabling spend caps.