Authentication

AgentBridge supports two authentication methods: API keys for server-to-server calls and AI agent integrations, and JWT session cookies for browser-based dashboard access. Most developers will use API keys exclusively.

Authentication Methods #

Choose the authentication method that matches your use case. You can use both methods simultaneously if your application has both server-side and browser-based components.

API Keys #

API keys are the primary authentication mechanism for programmatic access to the AgentBridge API. They identify your account, carry a set of permissions (scopes) that determine what operations are allowed, and are tied to a specific plan quota.

Creating an API Key #

1. Log in to the Dashboard

   Navigate to agentbridge.in and sign in with your account credentials. You must have verified your email before you can create API keys.

2. Open API Keys

   In the left sidebar, click API Keys. You will see a list of any existing keys for your account along with their name, scope, prefix, and creation date.

3. Click Create API Key

   Enter a descriptive name for the key (e.g. prod-agent, staging-ci, analytics-readonly). Select the desired scope from the dropdown: read, write, or admin.

4. Copy the key immediately

   Click Create. The full key is displayed exactly once in a dialog. Copy it immediately and store it in a secrets manager or password manager. You will not be able to view the full key again after closing the dialog.

Key Format #

All AgentBridge API keys follow a strict format that makes them easy to identify in code reviews and secret scanners:

ab_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789Ab
|       |                                      |
|       +---- 40 alphanumeric characters ------+
|
+-- prefix: identifies this as a live AgentBridge key

Using an API Key #

Pass the key as a Bearer token in the Authorization header on every request. The same header format works for all endpoints.

curl -X POST https://api.agentbridge.in/api/mcp/execute \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "notion",
    "tool": "create_page",
    "params": {
      "parent_id": "abc123",
      "title": "Hello from curl"
    }
  }'

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.agentbridge.in',
  headers: {
    'Authorization': `Bearer ${process.env.AGENTBRIDGE_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

const { data } = await client.post('/api/mcp/execute', {
  provider: 'slack',
  tool: 'send_message',
  params: { channel: 'C012AB3CD', text: 'Hello!' },
});

console.log(data.status); // "success"

import { AgentBridge } from 'agentbridge-sdk';

// Pass the key directly or let the SDK read AGENTBRIDGE_API_KEY from env
const bridge = new AgentBridge(process.env.AGENTBRIDGE_API_KEY!);

const result = await bridge.execute({
  provider: 'notion',
  tool:     'create_page',
  params:   { parent_id: 'abc123', title: 'Hello from SDK' },
});

console.log(result.data);        // { id: '...', url: '...' }
console.log(result.executionId); // "exec_01HXZ..."

Environment Variables #

Never hard-code your API key in source code. Store it as an environment variable and load it at runtime. This prevents accidental exposure through version control, logs, or error reports.

# AgentBridge API Key — never commit this file to source control
AGENTBRIDGE_API_KEY=ab_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Add .env to your .gitignore. For production deployments, use your platform's native secret management:

JWT Sessions #

JWT sessions are used by the AgentBridge Dashboard (browser). When you log in via POST /auth/login, the API sets an HTTP-only access_token cookie containing a signed JWT. Subsequent requests from the browser carry this cookie automatically. You do not need to manage JWTs manually unless you are building a custom browser-based client on top of the AgentBridge API.

Key Scopes #

API keys carry a scope that limits what operations they can perform. Always assign the minimum required scope for each key to follow the principle of least privilege.

Key Rotation #

Rotate API keys regularly (every 90 days is recommended) or immediately if you suspect a leak. Follow this four-step procedure for zero-downtime rotation:

1. Create a new key

   Go to Dashboard > API Keys > Create. Give it the same scope as the old key. Do not delete the old key yet. Both keys will work simultaneously during the transition.

2. Update your services

   Replace the old key value in all services, environment variables, secrets managers, and CI/CD pipelines. Deploy the changes to all environments that use the key.

3. Verify the new key

   Make a test API call with the new key to confirm it authenticates correctly. Check your execution logs to verify the call was logged under the new key name.

   bash — verify new key Copy

   curl https://api.agentbridge.in/integrations/providers \
     -H "Authorization: Bearer ab_live_NEW_KEY_HERE"

4. Delete the old key

   Once all services are using the new key, return to API Keys in the Dashboard and delete the old key. Requests using the deleted key will immediately return 401 Unauthorized.

Rate Limit Headers #

Every API response includes rate limit headers so you can monitor usage programmatically and avoid hitting limits. These headers are present on both successful and error responses.

const response = await fetch('https://api.agentbridge.in/api/mcp/execute', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ provider: 'notion', tool: 'search', params: { query: 'test' } }),
});

const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') ?? '0');
const resetAt   = parseInt(response.headers.get('X-RateLimit-Reset') ?? '0');

if (remaining < 10) {
  console.warn(`Low on quota: ${remaining} calls left. Resets at ${new Date(resetAt * 1000).toISOString()}`);
}

Authentication Error Responses #

When authentication fails, AgentBridge returns a structured JSON error. The two most common authentication errors are 401 and 403.

401 Unauthorized #

Returned when no API key is provided, the key is malformed (does not match the ab_live_ prefix + 40-char format), or the key has been revoked.

{
  "statusCode": 401,
  "message": "Invalid or missing API key",
  "error": "Unauthorized"
}

Common causes:

• The Authorization header is missing entirely
• The header value does not start with Bearer (note the trailing space)
• The key was deleted or revoked in the Dashboard
• A typo or truncation when copying the key
• Using a JWT token where an API key is expected (or vice versa)

403 Forbidden #

Returned when the key is valid but its scope does not permit the requested operation. For example, a read-scoped key trying to call POST /mcp/execute.

{
  "statusCode": 403,
  "message": "Insufficient scope. Required: write",
  "error": "Forbidden"
}

Resolution: Create a new key with the required scope. If you need write access for tool execution, select the write scope when creating the key. You cannot upgrade an existing key's scope; you must create a new key.

Security Best Practices #

• Never commit keys to source control. Use .env files locally (added to .gitignore) and a secrets manager in production. If a key is accidentally committed, rotate it immediately even if you force-push the commit away.
• Rotate keys every 90 days as a standard hygiene policy, and immediately after any team member with access departs or if you suspect a compromise.
• Use the minimum necessary scope. If your agent only reads data, give it the read scope. Most production agents need write. Reserve admin for internal tooling only.
• Create separate keys per environment (development, staging, production) so you can revoke a compromised environment's key without affecting others.
• Create separate keys per service. If you have multiple agents or microservices, give each its own key. This makes it easy to identify which service generated each log entry and revoke access granularly.
• Monitor your execution logs. Unexpected spikes in execution logs, unfamiliar tool names, or calls from unusual IP addresses may indicate a leaked key being abused.
• Use HTTPS exclusively. The AgentBridge API only accepts HTTPS. Plain HTTP requests are redirected with a 301. Never send API keys over unencrypted connections.
• Set up alerts for rate limit warnings. If your X-RateLimit-Remaining drops below a threshold, investigate whether the usage is legitimate or indicates abuse.