Custom API Keys

Custom API keys let you create additional keys beyond your main account key. Each key can have its own budget, expiration, and type, giving you fine-grained control over access and spending.

Use Cases

Environment separation — dedicated keys for development, staging, and production
Team access — separate keys for different team members or projects
Budget control — set credit limits per key to cap spending
Security — rotate or revoke individual keys without affecting other integrations
Usage tracking — monitor consumption per key

Token Types

Type	Description	Use Case
`api_token`	Production key with full access	Live applications
`sandbox_api_token`	Test key, no real provider calls	Development and testing

Sandbox keys return simulated responses and do not incur any cost. They are ideal for development and CI pipelines. See the Sandbox guide.

Two Ways to Manage Keys

From the dashboard. Any user can create, edit, rotate and revoke keys on the API Keys page. This is all you need for a handful of keys. Through the Management API. Organizations that provision keys from automation (CI, an internal portal, onboarding scripts) use the /v3/manage/keys endpoints documented below. These endpoints are not called with an inference key: they need a management key (mgmt-eden-…) with the manage:read scope to read and manage:write to create, update, rotate or revoke. Generate one from the dashboard (Account → Management Keys) or mint it with an issuer key, as explained in the Management API guide.

Calling a /v3/manage endpoint with an inference key (sk-eden-…) returns 401 with a message asking for a management key.

API Endpoints

All requests use Authorization: Bearer <management_key> and act on the organization the management key belongs to. Keys are addressed by their id (a UUID returned on create and in the list), not by name.

Endpoint	Method	Scope	Description
`/v3/manage/keys/`	`POST`	`manage:write`	Create a key. The response contains the `secret` once.
`/v3/manage/keys/`	`GET`	`manage:read`	List keys (paginated, revoked keys included).
`/v3/manage/keys/{key_id}/`	`GET`	`manage:read`	Get one key.
`/v3/manage/keys/{key_id}/`	`PATCH`	`manage:write`	Update the name or spending controls.
`/v3/manage/keys/{key_id}/`	`DELETE`	`manage:write`	Revoke a key permanently.
`/v3/manage/keys/{key_id}/rotate/`	`POST`	`manage:write`	Replace the secret, keeping the key’s id, name and settings.
`/v3/manage/keys/{key_id}/usage/`	`GET`	`manage:read`	Consumption of one key. See Monitoring.

The full request and response schemas are in the Organization Management section of the V3 API Reference.

Create a Key

import requests

headers = {
    "Authorization": "Bearer YOUR_MANAGEMENT_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.edenai.run/v3/manage/keys/",
    headers=headers,
    json={
        "name": "production-v1"
    }
)
response.raise_for_status()

key = response.json()
print(f"Created key {key['name']} (id: {key['id']})")
print(f"Secret (shown once, store it now): {key['secret']}")

curl -X POST https://api.edenai.run/v3/manage/keys/ \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-v1"}'

The response is the key resource plus a secret field:

{
  "id": "3f1c2b6e-8a4d-4f0e-9b7a-2c5d6e7f8a90",
  "name": "production-v1",
  "token_type": "api_token",
  "member": "owner@example.com",
  "masked": "sk-eden-…8a90",
  "active_balance": true,
  "balance": null,
  "expire_time": null,
  "revoked": false,
  "revoked_at": null,
  "secret": "sk-eden-..."
}

secret is returned only in this response and cannot be retrieved later. Store it immediately. If you lose it, rotate the key to get a new secret.

Request fields:

Field	Type	Description
`name`	string, required	Display name, unique among the owner’s active keys. A duplicate returns `409`.
`token_type`	`api_token` (default) or `sandbox_api_token`	Production or sandbox environment. Cannot be changed later.
`member`	email	Attribute the key to an organization member so their usage is reported per user. Omit it for a service key attributed to the organization itself.
`balance`	decimal string, e.g. `"50.00"`	Spending cap, enforced when `active_balance` is `true`.
`active_balance`	boolean, default `true`	Whether `balance` is enforced.
`expire_time`	ISO 8601 datetime	Hard expiry, at least one day ahead.
`balance_reset_period`, `balance_reset_amount`	see below	Periodic budget refill.

Creating a key returns 403 if your plan’s key limit is reached.

Create a Key with Budget

Set a spending limit with balance:

import requests

headers = {
    "Authorization": "Bearer YOUR_MANAGEMENT_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.edenai.run/v3/manage/keys/",
    headers=headers,
    json={
        "name": "team-backend",
        "token_type": "api_token",
        "balance": "50.00",
        "active_balance": True
    }
)
response.raise_for_status()

key = response.json()
print(f"Created key with ${key['balance']:.2f} budget")

curl -X POST https://api.edenai.run/v3/manage/keys/ \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "team-backend",
    "token_type": "api_token",
    "balance": "50.00",
    "active_balance": true
  }'

When active_balance is true, every API call deducts from the key’s balance. Once it reaches $0, the key stops working. In responses, balance is the remaining amount (a number), or null when the key has no spending cap.

Periodic Budget Reset

A budget can either reinitialize automatically each day, week, or month, or be a one-time allowance that stays at $0 once spent until you top it up manually. You control this with balance_reset_period (the reset frequency) and balance_reset_amount (the amount the balance is restored to at the start of each period).

In the dashboard

On the API Keys page, create or edit a key and turn on Spending Limit. Set the Reset allowance (the amount restored each period) and choose a Resets frequency — Daily, Weekly, Monthly, or Never. A reset frequency is always selected when a spending limit is on; it defaults to Monthly. Choose Never for a one-time budget that does not renew. A separate Current balance field shows what’s available right now; editing the allowance only takes effect at the next reset.

Through the API

import requests

headers = {
    "Authorization": "Bearer YOUR_MANAGEMENT_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.edenai.run/v3/manage/keys/",
    headers=headers,
    json={
        "name": "team-daily",
        "token_type": "api_token",
        "balance_reset_amount": "10.00",
        "balance_reset_period": "daily"
    }
)
response.raise_for_status()

key = response.json()
print(f"{key['name']} starts each day with ${key['balance']:.2f}")

curl -X POST https://api.edenai.run/v3/manage/keys/ \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "team-daily",
    "balance_reset_amount": "10.00",
    "balance_reset_period": "daily"
  }'

Field	Values	Meaning
`balance_reset_period`	`none`, `daily`, `weekly`, `monthly`	How often the balance is restored. `none` = one-time budget; it is the default when the field is omitted from the API request. (The dashboard instead pre-selects Monthly when you enable a spending limit.)
`balance_reset_amount`	positive amount	The value the balance is reset to each period. Required whenever the period is not `none`.

Behaviour to know:

Setting a reset period automatically enforces the budget (active_balance becomes true) — you don’t have to set it separately.
balance_reset_amount is the reset target, kept separate from the live balance (the amount remaining right now). They are not the same field.
A new periodic key starts the period full: if you don’t pass a starting balance, it begins at balance_reset_amount. Passing an explicit balance lets a key start partway through a period.
Resets run at midnight Europe/Paris time: daily every night, weekly on Monday, monthly on the 1st.
Setting the period back to none (with a PATCH) clears balance_reset_amount and returns the key to a one-time budget.

This per-key reset is distinct from the per-member budget cap you can set on a guardrail. A key budget is a hard cap on one key (it stops at $0); a member budget is a soft periodic spend cap that follows a person across all their keys.

List All Keys

The list is paginated (limit, max 100, and offset) and includes revoked keys, flagged with revoked: true. Secrets are never returned; use masked to recognise a key.

import requests

headers = {
    "Authorization": "Bearer YOUR_MANAGEMENT_KEY"
}

response = requests.get(
    "https://api.edenai.run/v3/manage/keys/",
    headers=headers,
    params={"limit": 100}
)
response.raise_for_status()

page = response.json()
print(f"{page['total_count']} key(s) in the organization")
for key in page["results"]:
    status = "revoked" if key["revoked"] else "active"
    print(f"{key['name']} | {key['token_type']} | balance: {key['balance']} | {status}")

curl -X GET "https://api.edenai.run/v3/manage/keys/?limit=100" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY"

{
  "results": [
    {
      "id": "3f1c2b6e-8a4d-4f0e-9b7a-2c5d6e7f8a90",
      "name": "production-v1",
      "token_type": "api_token",
      "member": "owner@example.com",
      "masked": "sk-eden-…8a90",
      "active_balance": true,
      "balance": null,
      "expire_time": null,
      "revoked": false,
      "revoked_at": null
    },
    {
      "id": "9d2e4a11-6c3b-4b8f-a1d0-7e6f5a4b3c21",
      "name": "team-backend",
      "token_type": "api_token",
      "member": "dev@example.com",
      "masked": "sk-eden-…3c21",
      "active_balance": true,
      "balance": 42.17,
      "expire_time": null,
      "revoked": true,
      "revoked_at": "2026-08-30T09:12:44Z"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total_count": 2,
  "next": null,
  "previous": null
}

A legacy key that was created before keys had ids and has never been regenerated is listed with "id": null. It cannot be addressed by URL until you regenerate it from the dashboard.

Update, Rotate or Revoke a Key

Follow-up operations take the key’s id. Only the fields you send in a PATCH are changed; token_type cannot be changed.

Update the budget

curl -X PATCH https://api.edenai.run/v3/manage/keys/3f1c2b6e-8a4d-4f0e-9b7a-2c5d6e7f8a90/ \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"balance": "100.00", "active_balance": true}'

Rotate the secret

curl -X POST https://api.edenai.run/v3/manage/keys/3f1c2b6e-8a4d-4f0e-9b7a-2c5d6e7f8a90/rotate/ \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY"

Rotating returns {"secret": "sk-eden-...", "masked": "...", "name": "production-v1"}. The previous secret stops working immediately and the new one is shown once.

Revoke

curl -X DELETE https://api.edenai.run/v3/manage/keys/3f1c2b6e-8a4d-4f0e-9b7a-2c5d6e7f8a90/ \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY"

Revoking is permanent: the key stops authenticating immediately, cannot be re-enabled, and stays in the list with revoked: true for your records. The response is 200 with the revoked key.

Best Practices

Use clear naming conventions like env-project-purpose (e.g., prod-billing-api, dev-ml-team) so keys are easy to identify at a glance.

Set budgets on non-production keys to prevent accidental overspending during development.
Use a periodic reset (balance_reset_period) for recurring allowances — e.g. a $10/day CI key — instead of topping up manually.
Use sandbox keys for CI/CD to validate integrations without incurring costs.
Rotate keys periodically with the rotate endpoint: the key keeps its id, name and budget, so nothing else needs to change.
Set expiration dates on temporary keys (e.g., for contractors or short-term projects).
Attribute keys to members with member so usage reports show who spent what.

V3 Documentation

Quick Start

Overview

LLMs

Expert Models

General

Organization

Data Governance

Integrations

Use Cases

Token Types

Two Ways to Manage Keys

API Endpoints

Create a Key

Create a Key with Budget

Periodic Budget Reset

In the dashboard

Through the API

List All Keys

Update, Rotate or Revoke a Key

Best Practices

​Use Cases

​Token Types

​Two Ways to Manage Keys

​API Endpoints

​Create a Key

​Create a Key with Budget

​Periodic Budget Reset

​In the dashboard

​Through the API

​List All Keys

​Update, Rotate or Revoke a Key

​Best Practices

Use Cases

Token Types

Two Ways to Manage Keys

API Endpoints

Create a Key

Create a Key with Budget

Periodic Budget Reset

In the dashboard

Through the API

List All Keys

Update, Rotate or Revoke a Key

Best Practices