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

1. Open API Keys settings

   In the dashboard, go to Settings → API Keys.

2. Create a key

   Click Create Key, enter a name (e.g., production), select the write scope, and confirm.

3. Copy the key

   The full key is displayed once. Copy it now.

   You cannot retrieve the full key after closing this dialog. If you lose it, revoke the key and create a new one.

Use the key in the SDK

Pass your key to agentvista.init():

import agentvista

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

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

import os, agentvista
agentvista.init(api_key=os.environ["AGENTVISTA_API_KEY"])

Use the key in HTTP requests

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

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:

curl https://api.agentvista.dev/api/v1/me/api-keys/ping/ \
  -H "Authorization: Bearer av_a1b2c3d4..."

{"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:

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.