Custom API Keys

Custom API keys let you create additional tokens beyond your main account key. Each token 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 token with full access	Live applications
`sandbox_api_token`	Test token, no real provider calls	Development and testing

Sandbox tokens return simulated responses and do not incur any cost. They are ideal for development and CI pipelines.

API Endpoints

Endpoint	Method	Description
`/v2/user/custom_token/`	`POST`	Create a new token
`/v2/user/custom_token/`	`GET`	List all tokens
`/v2/user/custom_token/{name}/`	`GET`	Get a specific token
`/v2/user/custom_token/{name}/`	`PATCH`	Update a token
`/v2/user/custom_token/{name}/`	`DELETE`	Delete a token

Create a Token

import requests

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

response = requests.post(
    "https://api.edenai.run/v2/user/custom_token/",
    headers=headers,
    json={
        "name": "production-v1"
    }
)

token = response.json()
print(f"Created token: {token['name']}")

curl -X POST https://api.edenai.run/v2/user/custom_token/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-v1"}'

Create a Token with Budget

Set a spending limit by enabling active_balance:

import requests

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

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

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

curl -X POST https://api.edenai.run/v2/user/custom_token/ \
  -H "Authorization: Bearer YOUR_API_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 token’s balance. Once it reaches $0, the token stops working.

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_API_KEY",
    "Content-Type": "application/json"
}

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

curl -X POST https://api.edenai.run/v2/user/custom_token/ \
  -H "Authorization: Bearer YOUR_API_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 token 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 clears balance_reset_amount and returns the token to a one-time budget.

This per-token reset is distinct from the per-member budget cap you can set on a guardrail. A token 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 Tokens

import requests

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

response = requests.get(
    "https://api.edenai.run/v2/user/custom_token/",
    headers=headers
)

tokens = response.json()
for t in tokens:
    print(f"{t['name']} | type: {t['token_type']} | balance: {t['balance']}")

curl -X GET https://api.edenai.run/v2/user/custom_token/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

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

Set budgets on non-production tokens 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 tokens for CI/CD to validate integrations without incurring costs.
Rotate tokens periodically — create a new token, migrate your application, then delete the old one.
Set expiration dates on temporary tokens (e.g., for contractors or short-term projects).

V3 Documentation

Quick Start

Overview

LLMs

Expert Models

General

Organization

Data Governance

Integrations

Use Cases

Token Types

API Endpoints

Create a Token

Create a Token with Budget

Periodic Budget Reset

In the dashboard

Through the API

List All Tokens

Best Practices

​Use Cases

​Token Types

​API Endpoints

​Create a Token

​Create a Token with Budget

​Periodic Budget Reset

​In the dashboard

​Through the API

​List All Tokens

​Best Practices

Use Cases

Token Types

API Endpoints

Create a Token

Create a Token with Budget

Periodic Budget Reset

In the dashboard

Through the API

List All Tokens

Best Practices