Manage Custom API Tokens

Learn how to create, manage, and organize custom API tokens for your Eden AI account.

Note: These are admin/dashboard endpoints typically used by the Eden AI dashboard or custom admin interfaces. For standard API authentication, see the Authentication Guide.

Overview

Custom tokens allow you to create additional API keys beyond your main account token. Use cases include:

Environment Separation - Different tokens for development, staging, and production
Team Access - Separate tokens for different team members or projects
Budget Control - Set credit limits per token to control spending
Security - Rotate or revoke tokens without affecting other integrations
Tracking - Monitor usage and costs per token for better analytics

Endpoints

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

Token Types

Eden AI supports two types of custom tokens:

Type	Description	Use Case
`api_token`	Production token with full access	Live applications, production environments
`sandbox_api_token`	Test token without real provider calls	Development, testing, demos

Creating Tokens

Create a Basic Token

Create a new custom token with just a name: Response:

{
  "name": "production-api-token",
  "token": "eyJhbG...1234567890abcdefghijklmnop",
  "token_type": "api_token",
  "balance": null,
  "active_balance": false,
  "expire_time": null
}

Important: Save the token value immediately - it’s only shown once during creation!

Create a Token with Credit Limit

Create a token with a spending limit: How Balance Works:

When active_balance is true, the token has a spending limit
Each API call deducts from the balance
When balance reaches $0, the token becomes unusable
Perfect for controlling costs per project or team

Create a Sandbox Token

Create a token for testing without real API calls: Sandbox Benefits:

No real provider API calls
No costs incurred
Returns mock data for testing
Perfect for development and CI/CD

Create a Token with Expiration

Create a temporary token that expires automatically:

Listing Tokens

List All Tokens

Get all your custom tokens: Response:

[
  {
    "name": "production-api-token",
    "token": "eyJhbG...1234567890abcdefghijklmnop",
    "token_type": "api_token",
    "balance": null,
    "active_balance": false,
    "expire_time": null
  },
  {
    "name": "dev-sandbox-token",
    "token": "eyJhbG...abcdef1234567890ghijklmnop",
    "token_type": "sandbox_api_token",
    "balance": null,
    "active_balance": false,
    "expire_time": null
  },
  {
    "name": "limited-budget-token",
    "token": "eyJhbG...xyz789abc123def456ghi789jk",
    "token_type": "api_token",
    "balance": 87.45,
    "active_balance": true,
    "expire_time": null
  }
]

Retrieving a Specific Token

Get details for a single token by name:

Updating Tokens

Update Token Balance

Add or adjust credit balance for a token:

Update Token Expiration

Extend or set expiration date:

Disable Balance Tracking

Remove balance limit from a token:

Deleting Tokens

Delete a custom token when no longer needed: Important: Deleting a token immediately revokes access. Any applications using that token will start receiving 401 authentication errors.

Best Practices

Token Naming Conventions

Use descriptive, consistent names:

# Good naming patterns
"prod-web-app"           # Environment + application
"staging-mobile-ios"     # Environment + platform
"dev-john-testing"       # Environment + developer
"ci-cd-pipeline"         # Purpose
"partner-acme-corp"      # External usage

# Avoid
"token1", "test", "temp"  # Too generic

Budget Control Strategy

Implement budget controls per token:

import requests

API_KEY = "eyJhbG...xxxxxxxxxxxxxxxxxxxxxxxx"

# Create tokens with appropriate budgets
token_configs = [
    {
        "name": "prod-main-app",
        "balance": "1000.00",  # High limit for production
        "active_balance": True
    },
    {
        "name": "staging-test-env",
        "balance": "50.00",  # Low limit for staging
        "active_balance": True
    },
    {
        "name": "dev-sandbox",
        "token_type": "sandbox_api_token",  # No cost
        "active_balance": False
    }
]

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

for config in token_configs:
    response = requests.post(
        "https://api.edenai.run/v2/user/custom_token/",
        headers=headers,
        json=config
    )
    print(f"Created: {config['name']}")

Token Rotation

Regularly rotate tokens for security:

import requests
from datetime import datetime, timedelta

API_KEY = "eyJhbG...xxxxxxxxxxxxxxxxxxxxxxxx"

def rotate_token(old_token_name: str, new_token_name: str):
    """
    Rotate a token by creating a new one and deleting the old one.
    """
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    # Get old token details
    old_response = requests.get(
        f"https://api.edenai.run/v2/user/custom_token/{old_token_name}/",
        headers=headers
    )
    old_token = old_response.json()

    # Create new token with same settings
    new_data = {
        "name": new_token_name,
        "token_type": old_token['token_type'],
        "active_balance": old_token['active_balance']
    }

    if old_token.get('balance'):
        new_data['balance'] = str(old_token['balance'])

    new_response = requests.post(
        "https://api.edenai.run/v2/user/custom_token/",
        headers=headers,
        json=new_data
    )

    new_token = new_response.json()

    print(f"New token created: {new_token['token']}")
    print("Update your application with the new token")
    print(f"Once confirmed, delete old token: {old_token_name}")

    return new_token

# Rotate quarterly
rotate_token("prod-q1-2024", "prod-q2-2024")

Monitor Token Usage

Track usage and remaining balance:

import requests

API_KEY = "eyJhbG...xxxxxxxxxxxxxxxxxxxxxxxx"

def check_token_health():
    """Check all tokens for low balance or expiration"""
    headers = {"Authorization": f"Bearer {API_KEY}"}

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

    tokens = response.json()

    for token in tokens:
        print(f"\nToken: {token['name']}")

        # Check balance
        if token.get('active_balance') and token.get('balance') is not None:
            if token['balance'] < 10:
                print(f"⚠️  LOW BALANCE: ${token['balance']:.2f}")
            else:
                print(f"✓ Balance: ${token['balance']:.2f}")

        # Check expiration
        if token.get('expire_time'):
            from datetime import datetime
            expiry = datetime.fromisoformat(token['expire_time'].replace('Z', '+00:00'))
            days_left = (expiry - datetime.now()).days

            if days_left < 7:
                print(f"⚠️  EXPIRES SOON: {days_left} days")
            else:
                print(f"✓ Expires in {days_left} days")

check_token_health()

Scope Limitations

Use different tokens for different scopes:

# Production tokens - full access
production_tokens = [
    {"name": "prod-us-east", "balance": "500"},
    {"name": "prod-eu-west", "balance": "500"}
]

# Development tokens - limited budget
dev_tokens = [
    {"name": "dev-feature-xyz", "balance": "25", "expire_time": "+30 days"},
    {"name": "dev-testing", "token_type": "sandbox_api_token"}
]

# External tokens - strict limits
external_tokens = [
    {"name": "partner-demo", "balance": "10", "expire_time": "+7 days"},
    {"name": "client-trial", "balance": "5", "expire_time": "+14 days"}
]

Error Handling

400 Bad Request

Invalid token name or parameters:

{
  "error": {
    "type": "validation_error",
    "message": {
      "name": ["Token with this name already exists."]
    }
  }
}

404 Not Found

Token doesn’t exist:

{
  "details": "Not Found"
}

403 Forbidden

Insufficient permissions:

{
  "error": {
    "type": "permission_error",
    "message": "You do not have permission to manage tokens"
  }
}

Next Steps

Multi-Environment Token Management Tutorial - Complete workflow
Monitor Usage and Costs - Track spending per token
Authentication Guide - Use your tokens

V3 Documentation

Manage tokens

Manage Custom API Tokens

Overview

Endpoints

Token Types

Creating Tokens

Create a Basic Token

Create a Token with Credit Limit

Create a Sandbox Token

Create a Token with Expiration

Listing Tokens

List All Tokens

Retrieving a Specific Token

Updating Tokens

Update Token Balance

Update Token Expiration

Disable Balance Tracking

Deleting Tokens

Best Practices

Token Naming Conventions

Budget Control Strategy

Token Rotation

Monitor Token Usage

Scope Limitations

Error Handling

400 Bad Request

404 Not Found

403 Forbidden

Next Steps

V3 Documentation

​Manage Custom API Tokens

​Overview

​Endpoints

​Token Types

​Creating Tokens

​Create a Basic Token

​Create a Token with Credit Limit

​Create a Sandbox Token

​Create a Token with Expiration

​Listing Tokens

​List All Tokens

​Retrieving a Specific Token

​Updating Tokens

​Update Token Balance

​Update Token Expiration

​Disable Balance Tracking

​Deleting Tokens

​Best Practices

​Token Naming Conventions

​Budget Control Strategy

​Token Rotation

​Monitor Token Usage

​Scope Limitations

​Error Handling

​400 Bad Request

​404 Not Found

​403 Forbidden

​Next Steps

Manage Custom API Tokens

Overview

Endpoints

Token Types

Creating Tokens

Create a Basic Token

Create a Token with Credit Limit

Create a Sandbox Token

Create a Token with Expiration

Listing Tokens

List All Tokens

Retrieving a Specific Token

Updating Tokens

Update Token Balance

Update Token Expiration

Disable Balance Tracking

Deleting Tokens

Best Practices

Token Naming Conventions

Budget Control Strategy

Token Rotation

Monitor Token Usage

Scope Limitations

Error Handling

400 Bad Request

404 Not Found

403 Forbidden

Next Steps