Authentication

The Banklyze API supports API key authentication and Bearer token authentication. Every request must include a valid credential. Unauthenticated requests receive a 401 Unauthorized response.

API Key Authentication

Include the X-API-Key header in every request:

curl -X GET https://api.banklyze.com/v1/deals \
  -H "X-API-Key: bk_abc123def456"

const response = await fetch("https://api.banklyze.com/v1/deals", {
  headers: {
    "X-API-Key": process.env.BANKLYZE_API_KEY!,
  },
});

import os, requests

response = requests.get(
    "https://api.banklyze.com/v1/deals",
    headers={"X-API-Key": os.environ["BANKLYZE_API_KEY"]},
)
print(response.json())

Bearer Token Authentication

As an alternative to API keys, you can authenticate using a Bearer token in the Authorization header. This is useful for session-based authentication or OAuth2 flows:

curl -X GET https://api.banklyze.com/v1/deals \
  -H "Authorization: Bearer your_session_token"

OAuth2 (Client Credentials)

For machine-to-machine integrations, you can obtain a short-lived access token via the OAuth2 client credentials flow:

curl -X POST https://api.banklyze.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

Use the returned access_token as a Bearer token in subsequent requests. Tokens expire after the duration specified in expires_in (seconds).

SSE / EventSource Authentication

Browser EventSource does not support custom headers. For Server-Sent Events connections, pass your API key or token as a query parameter:

// EventSource does not support custom headers.
// Use the token query parameter for SSE connections:
const source = new EventSource(
  "https://api.banklyze.com/v1/events/deals/42?token=your_api_key"
);

Generating & Rotating Keys

1. Sign in to the Banklyze dashboard.
2. Navigate to Settings → API Keys.
3. Click Generate New Key. Give it a descriptive label (e.g. “Production Backend” or “Staging Testing”).
4. Copy the key immediately — it will only be shown once.

You can also manage API keys programmatically via the API Keys endpoints: POST /v1/keys, GET /v1/keys, and DELETE /v1/keys/{key_id}.

To rotate a key:

1. Generate a new key and deploy it to your application.
2. Verify requests succeed with the new key.
3. Revoke the old key from the API Keys settings page.

You can have multiple active keys simultaneously, which makes zero-downtime rotation straightforward.

Key Format

Banklyze API keys use a recognizable prefix to help you identify them:

Rate Limiting

The API enforces a rate limit of 120 requests per minute per API key. Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1706000000

When you exceed the limit, the API returns 429 Too Many Requests:

{
  "detail": "Rate limit exceeded. Try again in 23 seconds.",
  "status_code": 429
}

Handling 429 responses: Check the X-RateLimit-Reset header and wait until that timestamp before retrying. Implement exponential backoff if you hit rate limits frequently.

Authentication Errors

Security Best Practices

• Never expose keys in client-side code. API keys should only be used in server-side applications, backend services, or CI/CD pipelines — never in browser JavaScript, mobile apps, or public repositories.
• Use environment variables. Store your API key in an environment variable (e.g. BANKLYZE_API_KEY) rather than hardcoding it in source code.
• Restrict key scope. Generate separate keys for each environment (development, staging, production) and each service that needs access.
• Rotate keys regularly. Rotate production keys at least every 90 days, and immediately if you suspect a key has been compromised.
• Monitor usage. Check the /api/v1/usage/me endpoint or the dashboard to spot anomalous request patterns.
• Use HTTPS only. All API requests must be made over HTTPS. HTTP requests will be rejected.