Authentication
How API keys are sent, validated, scoped, and provisioned.
Karybase public API endpoints authenticate with API keys. The API accepts either x-api-key or a Bearer token.
x-api-key: kb_live_...Authorization: Bearer kb_live_...If both headers are present, x-api-key is used.
Validation
Every protected request checks:
| Check | Behavior |
|---|---|
| Key hash | Raw keys are hashed before lookup |
| Enabled state | Disabled keys are rejected |
| Expiration | Expired keys are rejected |
| Usage limit | Keys with no remaining quota are rejected |
| Rate limit | Rate-limited keys are rejected after their configured window is exceeded |
| Permissions | Endpoint permission requirements are evaluated before data access |
Organization Scope
API keys are scoped to the organization that owns the key. Organization-scoped endpoints resolve the organization from the key, so clients do not need to send organizationId.
Passing a different organizationId as a legacy override returns an authorization error.
curl "https://api.karybase.com/api/v1/organization" \
-H "x-api-key: $KARYBASE_API_KEY"Inventory Permissions
Inventory endpoints require inventory view access:
inventory:viewThe API evaluates this against the key principal, organization features, role-derived permissions, and API-key custom permissions.
Provisioning
Organization owners and admins can create, list, and revoke API keys from Karybase organization settings. The server uses controlled provisioning templates:
| Template | Intended use |
|---|---|
read_only | Reporting and sync-read integrations |
read_write | Bidirectional integrations |
automation | High-frequency worker jobs |
Raw key material is returned only once at creation time. Store it in a secret manager.