Skip to main content

​
Authentication

AgentGate uses organization API keys to authenticate all API requests. This page explains how to create, use, and manage your API keys.

​
Overview

  • All API requests require authentication via API key
  • Keys are scoped to an organization, not individual users
  • Keys can have limited scopes for security
  • Use the Authorization header with Bearer token format

​
Organization API Keys

​
Key Format

AgentGate API keys follow this format: 
org_live_xxxxxxxxxxxxxxxxxxxxxxxx
  • org_ prefix identifies it as an organization key
  • live_ indicates a production key
  • The remaining characters are a unique identifier

​
Creating API Keys

1

Access API Key Settings

Log in to your AgentGate Dashboard and navigate to Settings → API Keys.
2

Create New Key

Click Create API Key and provide a descriptive name (e.g., “Production Backend”, “CI/CD Pipeline”).
3

Select Scopes

Choose the permissions your key needs. Use the principle of least privilege—only grant scopes that are necessary.
4

Copy and Store

Copy your API key immediately. It won’t be shown again. Store it securely in your environment variables or secrets manager.

​
Key Scopes and Permissions

API keys can be scoped to limit their capabilities:
ScopeDescription
work-orders:writeCreate work orders
work-orders:readRead work order details
runs:readRead run status and results
runs:writeCancel runs
credits:readCheck credit balance
webhooks:readList and view webhooks
webhooks:writeCreate, update, delete webhooks
templates:readList and view templates
templates:writeCreate, update, delete templates
*Full access (wildcard)
For development and testing, wildcard scope (*) is convenient. For production, use specific scopes.

​
Using API Keys

​
Header Format

Include your API key in the Authorization header: 
Authorization: Bearer org_live_xxxxxxxxxxxxxxxxxxxxxxxx

​
Examples

curl https://agentgate.mynewapi.com/v1/credits \
  -H "Authorization: Bearer org_live_xxxxxxxxxxxxxxxxxxxxxxxx"

​
Security Best Practices

​
Never Commit Keys to Source Control

Never commit API keys to Git repositories, even private ones. Use environment variables or secrets managers instead.
# Good: Use environment variables
export AGENTGATE_API_KEY=org_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Bad: Hardcoded in code
const apiKey = "org_live_xxxxxxxxxxxxxxxxxxxxxxxx"; // DON'T DO THIS

​
Use Environment Variables

Store keys in environment variables and access them in your code: 
const apiKey = process.env.AGENTGATE_API_KEY;
if (!apiKey) {
  throw new Error('AGENTGATE_API_KEY environment variable is required');
}

​
Minimum Necessary Scopes

Create keys with only the scopes needed for their specific use case:
  • Backend service: work-orders:write, runs:read, webhooks:write
  • Monitoring dashboard: runs:read, credits:read
  • CI/CD integration: work-orders:write, runs:read

​
Rotate Keys Periodically

Rotate API keys regularly and immediately if you suspect compromise:
  1. Create a new API key with the same scopes
  2. Update your applications to use the new key
  3. Verify applications work with the new key
  4. Revoke the old key

​
Key Rotation

​
When to Rotate

  • Regularly: Every 90 days as a best practice
  • Immediately: If a key may have been exposed
  • On team changes: When team members leave

​
Zero-Downtime Rotation

1

Create New Key

Create a new API key with identical scopes to the existing key.
2

Update Applications

Deploy your applications with the new API key.
3

Verify

Confirm all applications work correctly with the new key.
4

Revoke Old Key

Delete the old API key from the dashboard.

​
Troubleshooting

​
Common Errors

The API key is malformed or doesn’t exist.Solutions:
  • Verify the key format (org_live_...)
  • Check for typos or truncation
  • Ensure the key hasn’t been revoked
No API key was provided in the request.Solutions:
  • Ensure the Authorization header is present
  • Use the Bearer prefix
  • Check for header name typos
The API key doesn’t have the required scope.Solutions:
  • Check the key’s scopes in the dashboard
  • Create a new key with the required scopes
  • Review the endpoint’s required scopes in the API reference

​
Debugging Steps

  1. Verify the header format: Authorization: Bearer <key>
  2. Check key validity: Ensure the key exists in your dashboard
  3. Confirm scopes: Match required scopes with your key’s scopes
  4. Test with cURL: Isolate issues by testing directly with cURL

​
Next Steps

Quickstart

Make your first authenticated API call

API Reference

Explore all API endpoints