Skip to main content
public preview

These docs are a public preview. The endpoint reference is still firming up as the API host is finalized.

Authentication

Authenticate every request with an API key.

Overview

The Legba API uses API key authentication. Every request must include a valid API key in the Authorization header.

Important: Keep API keys secret. Never ship them in client-side code. Never commit them to public repositories.

Obtaining an API Key

To obtain an API key:

  1. Log in to your Legba organization dashboard
  2. Navigate to Settings → API Keys
  3. Click Generate New API Key
  4. Copy and securely store your API key

Save Your API Key

Your API key is shown once. Copy it immediately. Store it securely. If you lose it, generate a new one.

Making Authenticated Requests

Pass your API key in the Authorization header using the Bearer scheme:

curl -X GET "https://{your-api-host}/orgs/{org_uuid}/api/instances" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Authentication Errors

If authentication fails, the API returns a 401 Unauthorized response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Common Authentication Issues

Missing Authorization Header

Include the Authorization header in every request.

Incorrect Format

The header must use the format: Bearer YOUR_API_TOKEN

Expired or Revoked Key

API keys may expire or be revoked. Generate a new key if your current one stops working.

Security Best Practices

Store Keys Securely

Use environment variables or secret management services to store API keys. Never hardcode them in your source code.

Rotate Keys Regularly

Periodically rotate your API keys to minimize the impact of potential compromises. See API Keys for rotation instructions.

Use HTTPS Only

Always make API requests over HTTPS to ensure your API key is encrypted in transit.

Limit Key Scope

If your organization supports scoped keys, create keys with the minimum necessary permissions for your use case.

Monitor API Usage

Regularly review your audit logs to detect any unusual activity or unauthorized access attempts.

Next Steps

Authentication is set. Start making requests: