Authentication

Secure your API requests with API key authentication.

Overview

The Legba API uses API key authentication. All requests must include a valid API key in the Authorization header.

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 will only be shown once. Make sure to copy it immediately and store it securely. If you lose it, you'll need to generate a new one.

Making Authenticated Requests

Include your API key in the Authorization header using the Bearer authentication scheme:

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

Authentication Errors

If authentication fails, you'll receive a 401 Unauthorized response:

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

Common Authentication Issues

Missing Authorization Header

Ensure you 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

Now that you understand authentication, you're ready to start making API requests: