Authentication

Banklyze supports multiple authentication methods depending on your integration pattern. API keys are the simplest option and recommended for server-to-server integrations. Session tokens power the dashboard UI, and OAuth2 client credentials are available for enterprise integrations.

API Key Authentication

The simplest and most common way to authenticate. Pass your API key in the Authorization header as a Bearer token.

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

Never expose API keys in client-side code. API keys should only be used in server-side applications, background workers, and CI/CD pipelines.

Bearer Token Authentication

Session tokens are returned by the POST /auth/login endpoint and are used by the Banklyze dashboard. They are short-lived and scoped to the authenticated user.

# 1. Log in to get a session token
curl -X POST https://api.banklyze.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your_password"}'

# Response: { "token": "sess_abc123..." }

# 2. Use the session token
curl https://api.banklyze.com/v1/deals \
  -H "Authorization: Bearer sess_abc123..."

Session tokens expire after 24 hours of inactivity. The dashboard automatically refreshes them. For long-running integrations, use API keys instead.

OAuth2 (Client Credentials)

For enterprise integrations, Banklyze supports the OAuth2 client credentials flow. Exchange your client ID and secret for a time-limited access token.

# 1. Request an access token
curl -X POST https://api.banklyze.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

# Response:
# {
#   "access_token": "eyJhbG...",
#   "token_type": "Bearer",
#   "expires_in": 3600
# }

# 2. Use the access token
curl https://api.banklyze.com/v1/deals \
  -H "Authorization: Bearer eyJhbG..."

Name	Type	Required	Description
grant_type	string	Required	Must be "client_credentials"
client_id	string	Required	Your OAuth2 client ID
client_secret	string	Required	Your OAuth2 client secret

SSE / EventSource Authentication

Server-Sent Events (SSE) connections cannot set custom headers in the browser EventSource API. Pass your API key or session token as a query parameter instead.

SSE Authentication

// SSE connections pass the token as a query parameter
const url = new URL("https://api.banklyze.com/v1/events/stream");
url.searchParams.set("token", "bk_live_abc123def456");

const eventSource = new EventSource(url.toString());

eventSource.addEventListener("deal.updated", (event) => {
  const data = JSON.parse(event.data);
  console.log("Deal updated:", data.deal_id);
});

eventSource.addEventListener("document.processed", (event) => {
  const data = JSON.parse(event.data);
  console.log("Document processed:", data.document_id);
});

SSE token URLs will appear in server logs. Use a short-lived session token for SSE when possible, and ensure your server logs are properly secured.

Generating & Rotating Keys

API keys can be created and rotated from the dashboard or via the API. Each key can be scoped to specific permissions.

Create a new key

Generate API Key

# Generate a new API key
curl -X POST https://api.banklyze.com/v1/keys \
  -H "Authorization: Bearer sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Server", "scopes": ["deals:read", "deals:write", "documents:write"]}'

# Response:
# {
#   "data": {
#     "id": 7,
#     "name": "Production Server",
#     "key": "bk_live_sk_9f8a7b6c5d4e3f2a1b0c...",
#     "prefix": "bk_live_sk_9f8a",
#     "scopes": ["deals:read", "deals:write", "documents:write"],
#     "created_at": "2025-11-01T14:30:00Z"
#   }
# }

Rotate a key

Rotate API Key

# Rotate (regenerate) an existing key
curl -X POST https://api.banklyze.com/v1/keys/7/rotate \
  -H "Authorization: Bearer sess_your_session_token"

# The old key is immediately invalidated.
# The response contains the new key value.

Rotating a key immediately invalidates the old key. Update your applications before rotating production keys. Consider creating a new key first, migrating, then deleting the old one.

Key Format

All Banklyze API keys use the bk_ prefix, making them easy to identify in secret scanners and credential leak detection tools.

Key Prefixes

# Live keys (production)
bk_live_sk_9f8a7b6c5d4e3f2a1b0c...

# Test keys (sandbox)
bk_test_sk_1a2b3c4d5e6f7a8b9c0d...

Name	Type	Required	Description
bk_live_	prefix	Optional	Production keys. Requests hit live data and count against your usage quota.
bk_test_	prefix	Optional	Sandbox keys. Requests use isolated test data and do not affect production.

Rate Limiting

All API endpoints are rate-limited to protect service stability. Limits are applied per API key and vary by endpoint. When you exceed the limit, the API returns 429 Too Many Requests.

Rate limit headers

Every response includes headers to help you track your usage:

Name	Type	Required	Description
X-RateLimit-Limit	integer	Optional	Maximum number of requests allowed in the current window
X-RateLimit-Remaining	integer	Optional	Number of requests remaining in the current window
X-RateLimit-Reset	integer	Optional	Unix timestamp (seconds) when the rate limit window resets
Retry-After	integer	Optional	Seconds to wait before retrying (only present on 429 responses)

Default limits

Name	Type	Required	Description
Standard endpoints	1000/min	Optional	GET, PATCH, DELETE on most resources
Write endpoints	200/min	Optional	POST endpoints that create resources
Upload endpoints	30/min	Optional	Document upload and bulk ingest
Auth endpoints	10/min	Optional	Login, register, password reset

Security Best Practices

Store keys in environment variables

Never hardcode API keys in source code. Use environment variables or a secrets manager.

# .env — never commit this file
BANKLYZE_API_KEY=bk_live_sk_9f8a7b6c5d4e3f2a1b0c...

import os
from banklyze import Banklyze

# Reads BANKLYZE_API_KEY from environment automatically
client = Banklyze()

# Or pass explicitly
client = Banklyze(api_key=os.environ["BANKLYZE_API_KEY"])

Use the principle of least privilege

Create keys with only the scopes your application needs. A service that only reads deals should not have documents:write permission.

Rotate keys regularly

Rotate production keys on a regular schedule (e.g., every 90 days). Use the migration strategy: create new key, update services, then delete the old key.

Monitor usage

Review the Usage API and dashboard audit logs to detect unusual activity or unauthorized access.

Use HTTPS exclusively

All API requests must use HTTPS. The API will reject plain HTTP connections. Ensure your webhook endpoints also use HTTPS to protect payload data in transit.

Quickstart

Deals API Reference