Metalogue
Docs

Authentication

Configure API keys and manage access to the Metalogue API.

Authentication

Metalogue uses API keys for authentication. All API requests must include a valid API key.

API Keys

Creating an API Key

  1. Go to app.metalogue.xyz/settings/api-keys
  2. Click Create API Key
  3. Name your key (e.g., "Production", "Development")
  4. Select permissions (or use default for full access)
  5. Copy the key immediately—it won't be shown again

API Key Format

Metalogue API keys have the format:

mlo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The mlo_ prefix identifies Metalogue keys and enables faster validation.

Using Your API Key

Include the API key in the Authorization header:

curl -X POST https://api.metalogue.xyz/v1/federate \
  -H "Authorization: Bearer mlo_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "What was the auth decision?"}'

Or use the SDKs:

TypeScript:

const client = new MetalogueClient({
  apiKey: process.env.METALOGUE_API_KEY,
});

Python:

client = MetalogueClient(api_key=os.environ["METALOGUE_API_KEY"])

Go:

client := metalogue.NewClient(os.Getenv("METALOGUE_API_KEY"))

Environment Variables

We recommend storing API keys in environment variables:

# .env file
METALOGUE_API_KEY=mlo_your_api_key
METALOGUE_BASE_URL=https://api.metalogue.xyz  # Optional

Key Permissions

API keys can be scoped to specific permissions:

PermissionDescription
queryExecute federated queries
federateCross-node federation
connector:readList and view connectors
connector:writeCreate, update, delete connectors
audit:readView audit logs
audit:exportExport compliance reports

Creating Scoped Keys

// Admin action - not available in SDK
// Create via dashboard or Admin API

Rate Limits

API requests are rate-limited per API key:

PlanRequests/minRequests/hour
Free601,000
Pro30010,000
EnterpriseCustomCustom

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1706745600

When rate limited, you'll receive a 429 Too Many Requests response:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 42 seconds.",
  "retry_after": 42
}

SSO Authentication (Enterprise)

For enterprise deployments, Metalogue supports:

SAML 2.0

Configure your identity provider:

  1. Go to Settings → SSO → SAML
  2. Enter your IdP metadata URL or upload metadata XML
  3. Configure attribute mappings
  4. Test the connection

Required Attributes:

  • email (NameID or attribute)
  • name (optional)
  • groups (optional, for role mapping)

OIDC

Configure OpenID Connect:

  1. Go to Settings → SSO → OIDC
  2. Enter your Client ID and Client Secret
  3. Enter your Issuer URL
  4. Test the connection

Supported Providers:

  • Okta
  • Azure AD
  • Google Workspace
  • Auth0
  • OneLogin

Service Accounts

For machine-to-machine authentication (CI/CD, scheduled jobs):

// Service accounts use the same API key format
// but are not tied to a user

const client = new MetalogueClient({
  apiKey: process.env.METALOGUE_SERVICE_ACCOUNT_KEY,
});

Create service accounts in Settings → API Keys → Service Accounts.

Security Best Practices

  1. Never commit API keys to version control
  2. Use environment variables for all keys
  3. Rotate keys regularly (every 90 days recommended)
  4. Use scoped permissions when possible
  5. Monitor usage in the dashboard

Revoking Keys

To revoke an API key:

  1. Go to Settings → API Keys
  2. Find the key to revoke
  3. Click Revoke
  4. Confirm the action

Revoked keys are immediately invalidated.

Next Steps