API Keys

Overview

API Keys are authentication credentials that allow you to integrate aiXplain assets (agents, models, and tools) into your applications programmatically. They enable secure access to the aiXplain platform via the aiXplain SDK or REST API.

---

Accessing API Key Management

Location: Console > Settings > API Keys

Direct URL: https://console.aixplain.com/settings/keys

---

What Are API Keys?

API Keys are secure tokens that authenticate your applications when making requests to aiXplain services. They allow you to:

• Integrate assets - Use agents, models, and tools in your applications
• Create assets - Build agents and tools programmatically using the aiXplain SDK
• Access services - Make authenticated API calls to aiXplain endpoints
• Track usage - Monitor which key is consuming credits

---

Key Limits

Each workspace (personal or team) can create up to 10 API keys.

---

Types of API Keys

Standard API Keys

Used for general platform access including:

• Running agents via API
• Calling models directly
• Using tools programmatically
• Creating assets via SDK
• All inference and integration tasks

Use case: Application integration, programmatic asset creation, general API access

Admin Keys (Rate Limiting)

Special keys that allow Admins to set rate and usage limits for specific LLMs.

Important: Admin keys are only for rate limiting, not for inference.

Rate limits apply to:

• LLMs called directly via API
• LLMs used inside agents

Use case: Cost control, preventing runaway usage, enforcing organizational policies

Who can create: Admins and Owners only

---

Creating an API Key

Step-by-Step

1. Navigate to Console → Settings → API Keys
2. Click Create API Key
3. Enter a descriptive name for the key
   • Example: "Production Web App", "Dev Environment", "Mobile App - iOS"
4. (Optional) Add an expiration date
   • Set when the key should automatically expire
   • Leave blank for keys that don't expire
5. For Admin keys: Configure rate limits (if creating as Admin)
6. Click Create
7. Copy the key immediately - You won't be able to see it again

Important: Copy Immediately

After creation, the full API key is displayed once.

• Copy it immediately and store it securely
• You cannot retrieve the full key again after closing the dialog
• If you lose the key, you must delete it and create a new one

---

API Key Information

For each API key, you can see:

Information	Description
Name	Descriptive name you provided
Creator	Username of person who created the key
Created Date	When the key was generated
Expiration Date	When the key expires (if set)
Status	Active or Expired
Partial Key	Last few characters (e.g., ***xyz123)

Note: The full key is never displayed after creation. Only a partial key is shown for identification.

---

Managing API Keys

Copying Keys

After creation, you can copy the partial key identifier for reference, but you cannot retrieve the full secret key.

If you lose a key: Delete it and create a new one.

Deleting Keys

Who can delete:

• Personal workspace: Only you
• Team workspace: Admins and Owners

How to delete:

1. Go to Console → Settings → API Keys
2. Find the key you want to remove
3. Click the Delete button (trash icon)
4. Confirm deletion

What happens:

• The key is immediately revoked
• Any applications using this key will receive authentication errors
• The key cannot be restored

Best practice: Delete keys that are no longer in use to maintain security.

---

--

Using API Keys

With aiXplain SDK

The aiXplain SDK (Python) uses your API key for authentication.

Installation:

pip install aixplain

Authentication:

import aixplain

# Set your API key
aixplain.api_key = "your-api-key-here"

# Or use environment variable
# export AIXPLAIN_API_KEY="your-api-key-here"

Using assets:

# Run an agent
agent = aixplain.Agent("agent-asset-id")
response = agent.run("What is the weather today?")

# Use a model
model = aixplain.Model("model-asset-id")
result = model.run("Translate to French: Hello")

# Use a tool
tool = aixplain.Tool("tool-asset-id")
output = tool.run({"input": "data"})

Creating assets:

# Create an agent programmatically
agent = aixplain.Agent.create(
    name="My New Agent",
    description="An agent that helps with customer support",
    model="model-asset-id",
    tools=["tool-id-1", "tool-id-2"]
)

With REST API

Use API keys in the Authorization header.

Example request:

curl -X POST https://api.aixplain.com/v1/agents/run \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-asset-id",
    "query": "What is the weather today?"
  }'

With OpenAI-Compatible API

For models that support OpenAI API format:

from openai import OpenAI

client = OpenAI(
    api_key="your-aixplain-api-key",
    base_url="https://api.aixplain.com/v1"
)

response = client.chat.completions.create(
    model="model-asset-id",
    messages=[{"role": "user", "content": "Hello!"}]
)

---

Security Best Practices

Protect Your Keys

• Never commit keys to version control - Use environment variables or secrets management
• Don't share keys publicly - Keys grant full access to your workspace
• Use separate keys per application - Makes it easier to revoke if compromised
• Rotate keys regularly - Create new keys and delete old ones periodically
• Monitor key usage - Watch for unexpected activity

Key Storage

Good practices:

• Environment variables: export AIXPLAIN_API_KEY="your-key"
• Secret management services: AWS Secrets Manager, Azure Key Vault, HashiCorp Vault
• Encrypted configuration files
• CI/CD secrets (GitHub Secrets, GitLab CI Variables)

Bad practices:

• ❌ Hardcoded in source code
• ❌ Committed to Git repositories
• ❌ Stored in plain text files
• ❌ Shared via email or chat
• ❌ Included in client-side code (JavaScript)

Permissions

• Limit Admin access - Only give Admin role to those who need to manage keys
• Use principle of least privilege - Create keys with only necessary permissions
• Review keys regularly - Audit which keys exist and who created them
• Delete unused keys - Remove keys for deprecated applications

---

Admin Keys and Rate Limiting

What Are Admin Keys?

Admin keys allow you to enforce rate and usage limits on LLM usage to control costs and prevent abuse.

Important: Admin keys are for rate limiting only, not for making inference calls.

Who Can Create Admin Keys?

• Admins - Full key management including rate limiting
• Owners - Full key management including rate limiting
• Members - Cannot create Admin keys

Rate Limiting Capabilities

Admin keys can set limits on:

• Requests per minute - Maximum API calls per minute
• Tokens per day - Maximum token usage per day
• Credit budget - Maximum credits per time period
• Specific LLMs - Limits apply to designated models only

Use Cases for Admin Keys

Cost control:

• Prevent runaway costs from misconfigured agents
• Enforce budget caps per application
• Test environments with strict limits

Compliance:

• Meet regulatory requirements for AI usage
• Enforce company policies on LLM access
• Audit and control sensitive model usage

Resource management:

• Fair sharing among team members
• Prevent one app from consuming all resources
• Gradual rollout with increasing limits

Moving Between Workspaces

API keys are workspace-specific. When moving assets:

1. You cannot move keys between workspaces
2. Create new keys in the destination workspace
3. Update applications to use new keys
4. Delete keys from old workspace if no longer needed

---

Troubleshooting

"Invalid API Key" Error

Causes:

• Key was deleted
• Key has expired
• Key was copied incorrectly (missing characters)
• Using key from wrong workspace

Solutions:

1. Verify the key is still active in Console
2. Check expiration date
3. Ensure you copied the entire key
4. Confirm you're using the correct workspace's key

"Rate Limit Exceeded" Error

Causes:

• Admin key has rate limits configured
• Hitting platform-wide rate limits
• Too many concurrent requests

Solutions:

1. Check if key has Admin rate limits set
2. Implement exponential backoff in your code
3. Reduce request frequency
4. Contact support for higher limits (Enterprise plans)

"Insufficient Credits" Error

Cause:

• Workspace has run out of credits

Solution:

1. Add credits to the workspace
2. Check Console → Credits and Billing
3. Set up low credit alerts to prevent this

Key Not Working After Creation

Causes:

• Didn't copy the full key
• Workspace was switched after creation
• Key was created in different workspace

Solutions:

1. Verify you're using the correct workspace
2. Double-check the copied key has no extra spaces
3. If lost, delete and create new key