Betalink Docs

API Key Authentication

All API requests must include a valid API key in the X-API-Key header.

GET /api/v1/companies HTTP/1.1
Host: betalink.dev
X-API-Key: your-api-key

The Betalink API client handles this automatically:

const client = createBetalinkClient({
  baseUrl: "https://betalink.dev/api",
  apiKey: "your-api-key", // Automatically added to all requests
});

Obtaining an API Key

API keys are generated through the Betalink dashboard:

Log in to your Betalink account
Navigate to Settings > API Keys
Click Create New API Key
Copy and securely store your API key

Security Warning

API keys grant full access to your organization's data. Never expose them in client-side code, public repositories, or logs.

Security Best Practices

Environment Variables

Store your API key in environment variables:

const client = createBetalinkClient({
  baseUrl: process.env.BETALINK_API_URL!,
  apiKey: process.env.BETALINK_API_KEY!,
});

Server-Side Only

Only use the API client in server-side code:

// app/api/companies/route.ts (Next.js example)
export async function GET() {
  const client = createBetalinkClient({
    baseUrl: process.env.BETALINK_API_URL!,
    apiKey: process.env.BETALINK_API_KEY!,
  });

  const companies = await client.listCompanies();
  return Response.json(companies);
}

Key Rotation

Regularly rotate your API keys:

Generate a new API key
Update your application configuration
Verify the new key works
Revoke the old key

Rate Limiting

The API enforces rate limits to ensure fair usage:

Limit Type	Value
Requests per minute	60
Requests per hour	1,000

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200

Handling Rate Limits

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

import { RateLimitError } from "@betalink/api-client";

try {
  const companies = await client.listCompanies();
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    const retryAfter = error.retryAfter ?? 60;
    console.log(`Rate limited. Retry after ${retryAfter} seconds`);
  }
}

Retry Strategy

Implement exponential backoff for rate-limited requests:

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof RateLimitError && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

// Usage
const companies = await withRetry(() => client.listCompanies());

Error Responses

Authentication errors return appropriate HTTP status codes:

401 Unauthorized

Returned when the API key is missing or invalid:

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

429 Too Many Requests

Returned when rate limit is exceeded:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later.",
    "retryAfter": 60
  }
}

Authentication

On this page