Authentication

API Key Authentication

Agentbase uses API keys to authenticate requests. All API requests must include a valid API key in the Authorization header.

Getting Your API Key

Create an account at base.agentbase.sh/sign-up

Use your work email to get free credits automatically!

Access Dashboard

Copy API Key

Find your API key in the dashboard under Settings or API Keys

Using Your API Key

REST API
TypeScript SDK
Python SDK

Include your API key in the Authorization header:

curl -X POST https://api.agentbase.sh/run-agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, world!",
    "mode": "base"
  }'

Pass your API key when creating the client:

import Agentbase from "@agentbase/sdk";

const agentbase = new Agentbase({
  apiKey: process.env.AGENTBASE_API_KEY
});

Pass your API key when creating the client:

from agentbase import Agentbase

client = Agentbase(
    api_key=os.environ.get("AGENTBASE_API_KEY")
)

Security Best Practices

Never Commit API Keys

Don’t do this:

// ❌ Bad: API key in code
const agentbase = new Agentbase({
  apiKey: "agb_1234567890abcdef"
});

Do this instead:

// ✅ Good: API key in environment variable
const agentbase = new Agentbase({
  apiKey: process.env.AGENTBASE_API_KEY
});

Why: Committing API keys to version control exposes them to anyone with repository access.

Use Environment Variables

Store API keys in environment variables:

# .env file
AGENTBASE_API_KEY=agb_1234567890abcdef

// Load from .env
import dotenv from 'dotenv';
dotenv.config();

const agentbase = new Agentbase({
  apiKey: process.env.AGENTBASE_API_KEY
});

Note: Add .env to your .gitignore file.

Rotate Keys Regularly

Rotate your API keys periodically:

Create New Key

Generate a new API key in the dashboard

Update Applications

Update all applications to use the new key

Test Thoroughly

Verify all integrations work with the new key

Revoke Old Key

Once confirmed, revoke the old API key

Recommended schedule: Every 90 days or when team members leave

Server-Side Only

Never expose API keys in client-side code:

// ❌ Bad: API key in browser
const agentbase = new Agentbase({
  apiKey: "agb_1234567890abcdef"  // Visible to users!
});

Instead, proxy through your backend:

// ✅ Good: API key on server
// Frontend
const response = await fetch('/api/agent', {
  method: 'POST',
  body: JSON.stringify({ message: 'Hello' })
});

// Backend
app.post('/api/agent', async (req, res) => {
  const result = await agentbase.runAgent({
    message: req.body.message,
    mode: "base"
  });
  res.json(result);
});

Monitor Usage

Regularly review API usage in your dashboard:

Check for unexpected spikes
Monitor cost trends
Review active sessions
Identify anomalies

Set up alerts for unusual activity:

Sudden usage increases
Cost threshold exceeded
Failed authentication attempts

Error Handling

Handle authentication errors gracefully:

TypeScript
Python

try {
  const result = await agentbase.runAgent({
    message: "Hello",
    mode: "base"
  });
} catch (error) {
  if (error.status === 401) {
    console.error('Invalid API key');
    // Notify team, check configuration
  } else if (error.status === 403) {
    console.error('API key lacks permissions');
    // Check account status
  }
}

try:
    result = client.run_agent(
        message="Hello",
        mode="base"
    )
except AgentbaseError as e:
    if e.status_code == 401:
        print("Invalid API key")
        # Notify team, check configuration
    elif e.status_code == 403:
        print("API key lacks permissions")
        # Check account status

Common Errors

Error Code	Meaning	Solution
`401 Unauthorized`	Invalid or missing API key	Check your API key is correct and properly formatted
`403 Forbidden`	API key lacks permissions	Verify your account is active and has credits
`429 Too Many Requests`	Rate limit exceeded	Implement backoff and retry logic

Rate Limiting

Agentbase implements rate limiting to ensure fair usage:

Rate limits are applied per account
Limits vary by account tier

Headers include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Handling rate limits:

async function runAgentWithRetry(message: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await agentbase.runAgent({ message, mode: "base" });
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = error.headers["retry-after"] || Math.pow(2, i);
        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

Getting Started

Build

Deploy

Improve

Agent Primitives

API Reference

Resources

API Key Authentication

Getting Your API Key

Using Your API Key

Security Best Practices

Error Handling

Common Errors

Rate Limiting

​API Key Authentication

​Getting Your API Key

​Using Your API Key

​Security Best Practices

​Error Handling

​Common Errors

​Rate Limiting

API Key Authentication

Getting Your API Key

Using Your API Key

Security Best Practices

Error Handling

Common Errors

Rate Limiting