Skip to main content

Authentication

API keys, organization context, and request headers

2 min read

All KLOAKD API requests require two credentials: an API key and an organization ID.

API Key

Generate an API key from the dashboard: Settings → API Keys.

API keys are prefixed by tier:

| Prefix | Tier | Access | |--------|------|--------| | sk-live- | Developer / Enterprise | Full API access | | sk-test- | Playground | Read-only, rate-limited (used by Playground) |

The Playground tier offers 10 free discoveries with no signup. Test keys are identified by fingerprint + IP and have a permanent lifetime quota. See pricing for details.

Never expose your API key in client-side code or commit it to version control. Always use environment variables.

Request headers

Every API request must include:

| Header | Value | |--------|-------| | Authorization | Bearer <your-api-key> | | X-Kloakd-Organization | Your organization UUID | | Content-Type | application/json |

SDK configuration

Python

from kloakd import Kloakd

client = Kloakd(
    api_key="sk-live-...",
    organization_id="your-org-uuid",
)

TypeScript

import { Kloakd } from 'kloakd-sdk';

const client = new Kloakd({
  apiKey: 'sk-live-...',
  organizationId: 'your-org-uuid',
});

Go

client := kloakd.MustNew(kloakd.Config{
    APIKey:         "sk-live-...",
    OrganizationID: "your-org-uuid",
})

Java

Kloakd client = Kloakd.builder()
    .apiKey("sk-live-...")
    .organizationId("your-org-uuid")
    .build();

Environment variables

All SDKs read KLOAKD_API_KEY and KLOAKD_ORG_ID automatically when no explicit value is passed.

export KLOAKD_API_KEY=sk-live-...
export KLOAKD_ORG_ID=your-org-uuid

Request lifecycle

Every API request passes through a 5-stage gateway pipeline before reaching the handler:

  1. Authentication — validates your API key or JWT token
  2. Tenant resolution — resolves the organization from the credential
  3. IDOR protection — verifies the org_id in the URL path matches the credential's organization (prevents cross-tenant access)
  4. Entitlement check — confirms your plan includes the requested module
  5. Rate limiting & metering — enforces per-organization quotas and records usage

The organization ID in the URL must match the organization associated with your API key. Mismatched requests return 403 Forbidden — this is an intentional security control that prevents one tenant from accessing another's data.

Error responses

| Status | Error | Meaning | |--------|-------|---------| | 401 | AuthenticationError | Missing or invalid API key | | 403 | ForbiddenError | Organization ID mismatch (IDOR protection) | | 403 | NotEntitledError | Org not on required plan for this module | | 429 | RateLimitError | Per-organization quota exceeded |

Was this page helpful?
PreviousQuickstartNextConcepts