Managing API Keys

An Admin key can manage all of your other API keys through the API. Give each app, environment, or customer its own Inference key, cap what each one can spend, track usage per key, and change or revoke keys without opening the dashboard.

Create

Issue a key with a spend cap

Track

See what each key spends

Change

Raise a cap or extend an expiry

Revoke

Shut a key off right away

How it works

Admin keyYour control keyCreates, changes, and revokes keysReads usage and billingStays on your server

Inferencecust:acme$50 / monthPrivate models only

Inferencecust:globex$5 / monthOnly from 11.22.33.0/24

Inferencestaging$10 / dayExpires Jun 30

Admin keys can call every endpoint, including the ones that manage keys and read billing. Inference keys can call models but can’t manage keys or read billing, so they’re the keys you hand out.

	Admin	Inference
Call models and other inference endpoints	✓	✓
Check its own balance and rate limits (`GET /api_keys/rate_limits`)	✓	✓
Create, update, and revoke keys (`/api_keys`)	✓
Read usage and billing (`/billing/*`)	✓

Create your first Admin key in the dashboard: follow Generating an API Key and choose Admin as the key type. Keep it in a server-side secret store, never in client code.

The examples on this page read the Admin key from VENICE_ADMIN_KEY:

export VENICE_ADMIN_KEY="your-admin-key"

import os
import requests

BASE = "https://api.venice.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VENICE_ADMIN_KEY']}"}

const BASE = "https://api.venice.ai/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.VENICE_ADMIN_KEY}`,
  "Content-Type": "application/json",
};

Create a key

This creates an Inference key for one customer, capped at $50 a month and expiring on June 30, 2027:

curl https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": { "usd": 50 },
    "limitPeriod": "MONTH",
    "expiresAt": "2027-06-30"
  }'

resp = requests.post(f"{BASE}/api_keys", headers=HEADERS, json={
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": {"usd": 50},
    "limitPeriod": "MONTH",
    "expiresAt": "2027-06-30",
})
resp.raise_for_status()
key = resp.json()["data"]
key_id, secret = key["id"], key["apiKey"]

const res = await fetch(`${BASE}/api_keys`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    apiKeyType: "INFERENCE",
    description: "cust:acme",
    consumptionLimit: { usd: 50 },
    limitPeriod: "MONTH",
    expiresAt: "2027-06-30",
  }),
});
const { data: key } = await res.json();
const { id: keyId, apiKey: secret } = key;

Response

{
  "success": true,
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "apiKey": "VENICE_INFERENCE_KEY_...",
    "apiKeyType": "INFERENCE",
    "description": "cust:acme",
    "consumptionLimit": { "usd": 50, "vcu": null, "diem": null },
    "limitPeriod": "MONTH",
    "modelPrivacy": "ALL",
    "expiresAt": "2027-06-30T00:00:00.000Z",
    "ipAllowlist": []
  }
}

data.apiKey is the key’s secret, and this response is the only time you’ll see it. Store it right away. If it’s lost, revoke the key and create a new one. Keep data.id too: every other call on this page uses it.

Key settings

Set these when you create a key, or change them later with PATCH /api_keys. The request body is strict, so an unknown field returns 400.

Field	Values	What it does
`apiKeyType`	`INFERENCE` or `ADMIN`	Required on create. It can’t be changed later.
`description`	Up to 64 characters	Required on create. Usage analytics labels the key with it, so put your own identifier here, like `cust:acme`.
`consumptionLimit`	`{ "usd": 50 }`	Spend cap for each `limitPeriod`, in `usd`, `diem`, or both. Leave a currency out, or set it to `null`, for no cap. The USD cap counts USD, bundled credits, and earned credits together.
`limitPeriod`	`EPOCH`, `MONTH`, `LIFETIME`	When the cap resets. `EPOCH`, the default, resets daily at 00:00 UTC, `MONTH` on the 1st of each month (UTC), and `LIFETIME` never.
`expiresAt`	`"2027-06-30"`	A date, or a UTC time like `"2027-06-30T23:59:59Z"`. A date on its own means 00:00 UTC on that day. Leave it out for a key that never expires.
`modelPrivacy`	`ALL`, `PRIVATE_TEXT`, `PRIVATE_ONLY`	`ALL`, the default, allows any model. `PRIVATE_TEXT` requires Private, TEE, or E2EE text and embedding models. `PRIVATE_ONLY` requires that for every model.
`ipAllowlist`	`["11.22.33.0/24"]`	Up to 100 public IPv4 or IPv6 addresses or CIDR ranges. An empty list allows any IP.

You can create up to 20 keys a minute and keep up to 500 active keys. Contact support if you need more.

Building an agent? A wallet holding staked VVV on Base can mint its own key without a Venice account. See Autonomous Agent API Key Creation.

Track usage

To find out	Call	Read
What one key has spent this period	`GET /api_keys/{id}`	`currentPeriodUsage`
What each key spent in the last 7 days	`GET /api_keys`	`usage.trailingSevenDays`
Spend per key, by day	`GET /billing/usage-analytics`	`byKey`, `byKeyDaily`
Every charge, with the key it was billed to	`GET /billing/usage-history`	`apiKeyId`
Whether a key can spend right now	`GET /api_keys/rate_limits`, called with that key	`accessPermitted`, `balances`
Which keys are hitting rate limits	`GET /api_keys/rate_limits/log`	`apiKeyId`, `modelId`

One key

curl https://api.venice.ai/api/v1/api_keys/e28e82dc-9df2-4b47-b726-d0a222ef2ab5 \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

key = requests.get(f"{BASE}/api_keys/{key_id}", headers=HEADERS).json()["data"]

const res = await fetch(`${BASE}/api_keys/${keyId}`, { headers });
const { data: key } = await res.json();

Response (trimmed)

{
  "data": {
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "description": "cust:acme",
    "consumptionLimits": { "usd": 50, "diem": null, "vcu": null },
    "limitPeriod": "MONTH",
    "currentPeriodUsage": { "usd": "12.5000", "diem": "0.0000" },
    "usage": { "trailingSevenDays": { "usd": "4.2000", "diem": "0.0000", "vcu": "0.0000" } },
    "lastUsedAt": "2026-11-03T14:05:00.000Z"
  }
}

This key has used $12.50 of its $50 for the month. currentPeriodUsage only appears on keys with a USD or DIEM cap, and usage amounts are strings with four decimal places. Responses return consumptionLimits (plural), while requests send consumptionLimit (singular).

Spend per key over time

GET /billing/usage-analytics returns totals per key in byKey and one row per day in byKeyDaily, ready to chart. Pass lookback (7d by default, up to 90d) or a startDate and endDate pair that spans up to 90 days. Results are cached for 10 minutes.

cURL

curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

Response (trimmed)

{
  "byKey": [
    {
      "apiKeyId": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
      "description": "cust:acme",
      "totalUsd": 12.5,
      "totalDiem": 0,
      "totalUnits": 1830000
    }
  ]
}

Every charge, per key

GET /billing/usage-history lists every charge, and each entry carries the apiKeyId it was billed to. Use it to reconcile spend or bill your own customers. Entries come back oldest first. Send nextCursor back as cursor, on its own, until it’s null. Send Accept: text/csv to get CSV instead.

curl -G https://api.venice.ai/api/v1/billing/usage-history \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  --data-urlencode "startTimestamp=2026-10-01T00:00:00Z" \
  --data-urlencode "endTimestamp=2026-11-01T00:00:00Z"

from collections import defaultdict

spend = defaultdict(float)
params = {"startTimestamp": "2026-10-01T00:00:00Z", "endTimestamp": "2026-11-01T00:00:00Z"}
while True:
    page = requests.get(f"{BASE}/billing/usage-history", headers=HEADERS, params=params).json()
    for entry in page["data"]:
        if entry["apiKeyId"]:
            spend[(entry["apiKeyId"], entry["currency"])] -= entry["amount"]
    if page["nextCursor"] is None:
        break
    params = {"cursor": page["nextCursor"]}

Charges have a negative amount, so the loop subtracts it to get a positive total per key and currency. Entries without an apiKeyId come from the Venice web app, or are account entries such as credit purchases.

Whether a key can spend right now

GET /api_keys/rate_limits works with any key and reports on the key that calls it. accessPermitted says whether the key can spend right now, and balances shows what it has left to spend.

cURL

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

GET /api_keys/rate_limits/log, with an Admin key, returns your last 50 rate-limit hits, each with its apiKeyId and modelId.

Change limits and settings

Send the key’s id and only the fields you want to change. Everything else stays as it is. This raises the cap to $100 a month:

curl -X PATCH https://api.venice.ai/api/v1/api_keys \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e28e82dc-9df2-4b47-b726-d0a222ef2ab5",
    "consumptionLimit": { "usd": 100 }
  }'

requests.patch(f"{BASE}/api_keys", headers=HEADERS, json={
    "id": key_id,
    "consumptionLimit": {"usd": 100},
}).raise_for_status()

await fetch(`${BASE}/api_keys`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({ id: keyId, consumptionLimit: { usd: 100 } }),
});

Send any of these fields instead to make other changes:

To	Send
Remove the cap	`"consumptionLimit": { "usd": null }`
Reset the cap monthly instead of daily	`"limitPeriod": "MONTH"`
Make the cap a one-time budget	`"limitPeriod": "LIFETIME"`
Extend the expiry	`"expiresAt": "2027-12-31"`
Remove the expiry	`"expiresAt": null`
Only accept requests from your servers	`"ipAllowlist": ["11.22.33.0/24"]`
Accept requests from any IP again	`"ipAllowlist": []`
Allow only private models	`"modelPrivacy": "PRIVATE_ONLY"`
Rename the key	`"description": "cust:acme-prod"`

A new limitPeriod applies right away, so switching to LIFETIME counts all of the key’s past spend against the cap. apiKeyType can’t be changed; create a new key instead.

Revoke or rotate a key

curl -X DELETE \
  "https://api.venice.ai/api/v1/api_keys?id=e28e82dc-9df2-4b47-b726-d0a222ef2ab5" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

requests.delete(f"{BASE}/api_keys", headers=HEADERS, params={"id": key_id}).raise_for_status()

await fetch(`${BASE}/api_keys?id=${keyId}`, { method: "DELETE", headers });

The response is { "success": true }. Revocation is immediate: the key’s next request gets 401 Authentication failed, and the key drops out of GET /api_keys. Its past charges stay in usage history. To rotate a key without downtime:

Create the replacement

Create a new key with the same settings and store its secret.

Deploy it

Switch your app over to the new secret.

Revoke the old key

Once the old key’s lastUsedAt in GET /api_keys stops moving, delete it.

Errors your callers may see

Status	Message	What to do
`402`	`API key USD spend limit exceeded...`, or the same for DIEM	Raise or remove the cap, or wait for the next period. The account itself may still have funds.
`403`	The model isn’t allowed by the key’s privacy setting	Use a Private, TEE, or E2EE model, or change `modelPrivacy`.
`403`	`This API key is restricted to configured IP addresses...`	Add the caller’s IP to `ipAllowlist`.
`401`	`Authentication failed`	The key is revoked, expired, or mistyped.
`401`	`Admin API key required`	An Inference key called a key management or billing endpoint.
`429`	`Too many API key creation requests...`	Key creation is limited to 20 a minute. Wait, then retry.
`400`	`Maximum number of active API keys (500) reached...`	Revoke keys you no longer use, or contact support.

See Error Codes for the full list.

Best practices

Keep Admin keys on your server, and hand out only Inference keys.
Give every app, environment, and customer its own key, so each one can be tracked and revoked on its own.
Put your own identifier in description. Usage analytics labels keys with it.
Cap and expire every key you give to someone else, and lock server-to-server keys to your IPs with ipAllowlist.

API reference

Create API Key

All fields accepted on create.

Update API Key

Change limits, expiry, privacy, and IPs.

List API Keys

Every active key with its usage.

Delete API Key

Revoke a key.

Usage Analytics

Spend by key, model, and day.

Usage History

Every charge, with its API key.

Docs

Getting Started

Text & Chat

Image

Video

Audio

Search & RAG

Agents & Integrations

Coding Tools

Agent Tooling

SDKs & Frameworks

Create

Track

Change

Revoke

How it works

Create a key

Key settings

Track usage

One key

Spend per key over time

Every charge, per key

Whether a key can spend right now

Change limits and settings

Revoke or rotate a key

Errors your callers may see

Best practices

API reference

Create API Key

Update API Key

List API Keys

Delete API Key

Usage Analytics

Usage History

Create

Track

Change

Revoke

​How it works

​Create a key

​Key settings

​Track usage

​One key

​Spend per key over time

​Every charge, per key

​Whether a key can spend right now

​Change limits and settings

​Revoke or rotate a key

​Errors your callers may see

​Best practices

​API reference

Create API Key

Update API Key

List API Keys

Delete API Key

Usage Analytics

Usage History

How it works

Create a key

Key settings

Track usage

One key

Spend per key over time

Every charge, per key

Whether a key can spend right now

Change limits and settings

Revoke or rotate a key

Errors your callers may see

Best practices

API reference