API keys authenticate programmatic access to Rivano. Keys are prefixed with rv_ followed by the scope. The key string is only returned once — at creation time.

GET /api/keys

List all API keys for the current tenant

Returns key metadata only. The key string is never returned after creation.

Parameters:

Param	Type	Description
`limit`	number	Max results (default 50)
`offset`	number	Pagination offset
`scope`	string	Filter by scope: `api`, `agent`, `ingest`

Response (200):

{
  "data": [
    {
      "id": "key_abc123",
      "name": "ci-pipeline",
      "scope": "ingest",
      "prefix": "rv_ingest_abc1",
      "createdBy": "user_xyz789",
      "createdByEmail": "alice@example.com",
      "lastUsedAt": "2026-04-04T09:45:00Z",
      "createdAt": "2026-01-15T10:00:00Z"
    },
    {
      "id": "key_def456",
      "name": "monitoring-script",
      "scope": "agent",
      "prefix": "rv_agent_def4",
      "createdBy": "user_xyz789",
      "createdByEmail": "alice@example.com",
      "lastUsedAt": "2026-04-03T18:20:00Z",
      "createdAt": "2026-02-01T12:00:00Z"
    }
  ],
  "total": 4,
  "limit": 50,
  "offset": 0
}

import Rivano from '@rivano/sdk';
const rivano = new Rivano({ apiKey: process.env.RIVANO_API_KEY! });

const keys = await rivano.keys.list();
keys.data.forEach(k => console.log(k.name, k.scope, k.prefix));

curl https://api.rivano.ai/api/keys \
  -H "Authorization: Bearer rv_api_..."

POST /api/keys

Create a new API key

⚠

The key field in the response is only returned once. Copy it immediately and store it in your secrets manager. There is no way to retrieve it again — if you lose it, delete the key and create a new one.

Request body:

{
  "name": "production-gateway",
  "scope": "ingest"
}

Field	Required	Description
`name`	Yes	Human-readable name for the key
`scope`	Yes	`api`, `agent`, or `ingest`

Response (201):

{
  "data": {
    "id": "key_xyz789",
    "name": "production-gateway",
    "scope": "ingest",
    "key": "rv_ingest_xyz789abcdefghijklmnopqrstuvwxyz1234567890",
    "prefix": "rv_ingest_xyz7",
    "createdBy": "user_abc123",
    "createdAt": "2026-04-04T10:00:00Z"
  }
}

The key field is present only in this creation response. Subsequent GET requests return the prefix field instead.

const result = await rivano.keys.create({
  name: 'production-gateway',
  scope: 'ingest',
});

// Save this — it won't be shown again
const apiKey = result.data.key;
console.log('New key:', apiKey);

curl -X POST https://api.rivano.ai/api/keys \
  -H "Authorization: Bearer rv_api_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "production-gateway", "scope": "ingest"}'

DELETE /api/keys/:id

Delete an API key

The key is invalidated immediately. Any service using the deleted key will receive 401 Unauthorized on its next request.

Response (200):

{ "success": true }

await rivano.keys.delete('key_abc123');

curl -X DELETE https://api.rivano.ai/api/keys/key_abc123 \
  -H "Authorization: Bearer rv_api_..."

Key scopes

Scope	Prefix	Use case
`api`	`rv_api_`	Admin automation — full read/write to all resources
`agent`	`rv_agent_`	Read-only access to agents and traces
`ingest`	`rv_ingest_`	Gateway proxy — write trace data

Use the least-permissive scope for each use case. Never embed api-scoped keys in application code that runs in production environments.

Key rotation workflow

Create a new key with the same scope and a versioned name (e.g. gateway-v2).
Deploy the new key to your environment.
Monitor for successful requests using the new key (lastUsedAt on the new key should update).
Delete the old key.

The window between step 2 and step 4 is your rotation window — both keys are valid simultaneously.

Authentication — How keys authenticate requests
RBAC — Key scopes and permission model
API Reference Overview — Using keys in request headers
Dashboard API Keys — Settings → API Keys UI

API Keys

Key scopes

Key rotation workflow

Related