venice-api-keys

# Venice API Keys

Admin endpoints for managing Bearer API keys. You need an **ADMIN** key (or parent session) to call these. For wallet-only auth, use [`venice-auth`](../venice-auth/SKILL.md) / [`venice-x402`](../venice-x402/SKILL.md) instead.

| Endpoint | Purpose |
|---|---|
| `GET /api_keys` | List your keys (masked). |
| `POST /api_keys` | Create a new key. Response contains the **only copy of the secret**. |
| `PATCH /api_keys` | Update `description`, `expiresAt`, `consumptionLimit`. |
| `DELETE /api_keys?id=...` | Revoke a key. |
| `GET /api_keys/{id}` | Full details for one key (usage, limits, expiration). |
| `GET /api_keys/rate_limits` | Balances + per-model rate-limit tiers for the current key. |
| `GET /api_keys/rate_limits/log` | Last 50 rate-limit breaches. |
| `GET /api_keys/generate_web3_key` | Get a SIWE-style token to sign with a wallet. |
| `POST /api_keys/generate_web3_key` | Authenticate a wallet (holds sVVV) and mint a classic API key. |

Limits: key creation is capped at **20 requests/minute** and **500 active keys per user**.

## Key types

| Type | Can call |
|---|---|
| `INFERENCE` | Inference endpoints plus any route that only requires authentication — e.g. `/chat/*`, `/image/*`, `/audio/*`, `/video/*`, `/embeddings`, `/augment/*`, `/crypto/rpc`, `/characters`, `/api_keys/rate_limits*`, `/support-bot`. Rejected from admin routes listed below with `401`. |
| `ADMIN` | Everything an `INFERENCE` key can do, plus admin-only routes: `POST/PATCH/DELETE /api_keys`, `GET /api_keys` (list), `GET /api_keys/{id}`, `GET /billing/balance`, `GET /billing/usage`. |

A leaf app should almost always use **`INFERENCE`** keys — per-app, per-user, with consumption caps.

## `GET /api_keys`

```bash
curl https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $ADMIN_KEY"
```

Returns:

```json
{
  "object": "list",
  "data": [
    {
      "id": "uuid",
      "apiKeyType": "INFERENCE",
      "description": "backend prod",
      "createdAt": "2025-10-01T12:00:00Z",
      "expiresAt": null,
      "lastUsedAt": "2026-04-20T10:05:00Z",
      "last6Chars": "2V2jNW",
      "consumptionLimits": { "usd": 50, "diem": 10 },
      "usage": { "trailingSevenDays": { "usd": "4.20", "diem": "0.00" } }
    }
  ]
}
```

The full secret is **never** returned on list — only `last6Chars`.

## `POST /api_keys` — create

```bash
curl https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyType": "INFERENCE",
    "description": "backend prod",
    "expiresAt": "2026-12-31T23:59:59Z",
    "consumptionLimit": { "usd": 50, "diem": 10 }
  }'
```

Response includes the **one-time** `apiKey` secret:

```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "apiKey": "VENICE_INFERENCE_KEY_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "apiKeyType": "INFERENCE",
    "description": "backend prod",
    "expiresAt": "2026-12-31T23:59:59Z",
    "consumptionLimit": { "usd": 50, "diem": 10 }
  }
}
```

**Save it immediately** — Venice won't show the secret again. If you lose it, delete and re-create.

### Required

- `apiKeyType`
- `description`

### Optional

- `expiresAt` — empty string or ISO 8601 date/datetime. Omit for non-expiring.
- `consumptionLimit.usd` / `.diem` — per-epoch caps. Null means no cap on that currency.
- `consumptionLimit.vcu` — **deprecated** (legacy Diem). Use `diem` instead.

## `PATCH /api_keys` — update

```bash
curl -X PATCH https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "uuid", "description": "renamed", "consumptionLimit": { "usd": 100 } }'
```

Only `description`, `expiresAt`, and `consumptionLimit` are mutable. Pass `"expiresAt": ""` or `null` to remove an expiration.

## `DELETE /api_keys?id=<uuid>` — revoke

```bash
curl -X DELETE "https://api.venice.ai/api/v1/api_keys?id=uuid" \
  -H "Authorization: Bearer $ADMIN_KEY"
```

Returns `{"success": true}`. Revocation is immediate.

## `GET /api_keys/{id}` — details

Returns one key's full metadata plus trailing-7-day usage. Useful for an admin dashboard row view.

## `GET /api_keys/rate_limits`

```bash
curl https://api.venice.ai/api/v1/api_keys/rate_limits \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

Returns for the calling key:

```json
{
  "data": {
    "accessPermitted": true,
    "apiTier": { "id": "paid", "isCharged": true },
    "balances": { "USD": 50.23, "DIEM": 100.023 },
    "keyExpiration": "2025-06-01T00:00:00Z",
    "nextEpochBegins": "2025-05-07T00:00:00.000Z",
    "rateLimits": [
      {
        "apiModelId": "zai-org-glm-5-1",
        "rateLimits": [
          { "type": "RPM", "amount": 100 },
          { "type": "TPM", "amount": 200000 },
          { "type": "RPD", "amount": 10000 }
        ]
      }
    ]
  }
}
```

Use it to:

- Display current balances in-app.
- Warm-gate calls when the relevant model's RPM cap is near.
- Know when the next epoch resets (DIEM, bundled credits).

## `GET /api_keys/rate_limits/log`

Returns the last 50 rate-limit breaches. Response is wrapped as `{ object: "list", data: [...] }`:

```json
{
  "object": "list",
  "data": [
    { "apiKeyId": "...", "modelId": "zai-org-glm-5-1", "rateLimitType": "RPM",
      "rateLimitTier": "paid", "timestamp": "2026-04-20T12:34:56Z" }
  ]
}
```

Feed these into your monitoring when tuning concurrency.

## Web3 API keys — two-step wallet flow

Lets a wallet that **holds sVVV** mint a classic Bearer API key. No Venice account required.

### 1. `GET /api_keys/generate_web3_key`

```bash
curl https://api.venice.ai/api/v1/api_keys/generate_web3_key
```

Returns `{ success: true, data: { token: "<jwt-ish token>" } }`.

### 2. Sign the token with your wallet, then `POST /api_keys/generate_web3_key`

```ts
import { Wallet } from 'ethers'

const { data: { token } } = await fetch(`${base}/api_keys/generate_web3_key`).then(r => r.json())
const wallet = new Wallet(pr