Skip to main content
KalinkloOS
Developer portal

Developer docs

Auth and Rate Limits

Bearer-token scheme, key lifecycle, rate-limit headers, and retry policy.

Authentication

The organization API is scoped to a single workspace and requires a bearer token in the Authorization header:

Authorization: Bearer abo_org_xxxxxxxx
Accept: application/json

Organization keys follow the shape abo_org_<random>. They are stored only as a salted hash, compared in constant time, and carry an explicit scope list. There is no separate test key or test workspace: a key acts on the workspace it was issued for.

The public marketplace read endpoints require no token at all — see Public Endpoints.

Error codes you can rely on:

  • Missing or malformed Authorization → 401 with error.code = "API_KEY_MISSING"
  • A token that is unknown, revoked or not valid for this workspace → 401 with error.code = "API_KEY_INVALID"
  • A valid token lacking the scope for the action → 403 with error.code = "API_SCOPE_MISSING"

A key issued for one workspace and used against another returns 404, never 403, so workspace slugs cannot be enumerated by probing.

Key lifecycle

Keys are issued by Kalinklo Operations during approved integration onboarding — request access at /pilot. Self-serve console issuance is not available yet.

A key can be revoked, which takes effect immediately. There is no rotation grace window: issue the replacement key, migrate your client to it, then revoke the old one.

Rate limits

Rate limits are enforced per key and, on public endpoints, per IP. Exceeding a limit returns 429.

Rate-limit headers (X-RateLimit-*, Retry-After) are not currently emitted. Treat a 429 as the signal and back off as below.

Retry policy

For transient errors (429, 502, 503, 504):

  1. Wait at least 1 second before the first retry.
  2. Apply exponential backoff capped at 30 seconds.
  3. Add jitter of ±20% to avoid thundering-herd retries.
  4. Stop after 5 attempts; surface the error to the operator.

Do not retry 4xx errors except 429. They will not succeed without changing the request.

Security

  • Never embed keys in browser bundles or mobile apps. Use a server-side proxy.
  • Keep keys in environment variables, not source control.
  • Use a distinct key per integration, so one can be revoked without disrupting the others.
  • Revoke immediately on suspected exposure — revocation takes effect at once.

Where to next

Auth and Rate Limits · Developer Docs | Kalinklo