API keys

Create, list, and revoke API keys for authenticating with the AgentVista API.

API keys authenticate requests to AgentVista ingestion and management endpoints. Every key starts with av_ and carries one or more scopes that control what it can access.

When you create a key, AgentVista returns the full key value exactly once. Copy it immediately — it is never shown again. Only a short prefix (e.g. av_a1b2c3d4) is stored and returned in subsequent list responses.

Scopes

Scope	Description
write	Required for all ingestion endpoints (/traces/batch, /otlp/v1/*)
read	Required to verify a key with the ping endpoint

---

List API keys

cURL

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

GET /me/api-keys/

Returns a paginated list of API keys for the authenticated user. The raw key value is never included in list responses.

Query parameters

page · number · default: "1"

Page number (1-indexed).

page_size · number · default: "20"

Number of keys per page.

Response

results · object[]

Array of API key objects.

Show key object fields

id · string

UUID of the key.

name · string

Human-readable label for this key.

scopes · string[]

List of scopes granted to this key, e.g. ["write"].

prefix · string

The first characters of the key used for identification in list views (e.g. av_a1b2c3d4). Not the full key.

is_active · boolean

Whether the key can authenticate requests. Revoked keys have is_active: false.

org_slug · string | null

Organization slug the key is scoped to, or null for personal keys.

last_used_at · string | null

ISO 8601 timestamp of the last successful authenticated request, or null if never used.

usage_count · number

Total number of authenticated requests made with this key.

created_at · string

ISO 8601 timestamp when the key was created.

---

Create an API key

cURL

curl -X POST https://api.agentvista.dev/api/v1/me/api-keys/ \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-ingest",
    "scopes": ["write"]
  }'

POST /me/api-keys/

Creates a new API key and returns the full raw key value. Store it immediately.

Request body

name · string

A human-readable label to identify this key (e.g. production-ingest). Optional but recommended.

scopes · string[] · required

List of scopes to grant. Must contain at least one valid scope. Use ["write"] for ingestion.

org_slug · string

Organization slug to scope this key to. If omitted, the key is a personal key tied to your user account.

Response — 201

id · string

UUID of the new key.

name · string

Label you provided.

scopes · string[]

Scopes granted to this key.

prefix · string

Short prefix for identification in list views.

is_active · boolean

Always true on creation.

org_slug · string | null

Organization slug or null.

created_at · string

ISO 8601 creation timestamp.

key · string

The full raw API key. Copy this now — it is never returned again.

Example response

{
  "id": "3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a",
  "name": "production-ingest",
  "scopes": ["write"],
  "prefix": "av_a1b2c3",
  "is_active": true,
  "org_slug": null,
  "created_at": "2024-01-15T10:00:00Z",
  "key": "av_a1b2c3d4e5f6..."
}

---

Verify a key

cURL

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

GET /me/api-keys/ping/

Verifies that an API key is valid and has read scope. Useful for checking a key works before deploying.

Response — 200

status · string

Always "ok" when the key is valid and has read scope.

{ "status": "ok" }

---

Revoke an API key

cURL

curl -X DELETE https://api.agentvista.dev/api/v1/me/api-keys/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a/ \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

DELETE /me/api-keys/{key_id}/

Immediately revokes the key. Any subsequent requests using the revoked key receive 401.

Path parameters

key_id · string · required

UUID of the key to revoke.

Response — 204

No body. The key has been revoked.