Get started

Authentication

Every request carries a bearer token in the Authorization header. Use an API key for your own integration with one workspace, and OAuth when you build an app that many workspaces install.

API keys

An API key belongs to one workspace and acts on its own behalf, not as a person. Owners and admins create keys in Settings → Developers; other roles cannot see or create them, and keys cannot be managed through the API with another key.

curl https://api.kweko.uz/v1/leads \
  -H "Authorization: Bearer kwk_live_…"

• Format. kwk_live_, 40 random letters and digits, _ and a 6-character checksum. The checksum lets Kweko reject a mistyped key before it looks anything up.
• Shown once. Kweko stores only a keyed hash. If a key is lost, rotate it or create a new one.
• Scopes. Each key has a fixed list of scopes, chosen when it is created. Two presets exist: read only (every :read scope except messages:read and export:read) and full (every scope).
• Expiry. 30, 90 or 365 days, or never. The default is 90 days. An expired key answers key_expired.
• IP allowlist. Optionally up to 20 IP addresses or CIDR ranges. Requests from elsewhere answer ip_not_allowed.
• Limits. Up to 50 active keys per workspace.
• Last used. Kweko records when and from which IP a key was last used (updated at most once a minute) and keeps a request log for 7 days, both visible in Settings → Developers.

Rotation and revocation

Rotating a key gives it a new secret. The old secret keeps working for 24 hours, so you can deploy the new one without downtime; choose revoke old now to stop it at once. After the overlap the old secret answers key_revoked. Revoking a key stops it immediately and for good.

Where keys are accepted

• Only on https://api.kweko.uz/v1/…, the public API. A key sent anywhere else answers unauthenticated.
• Only in the Authorization: Bearer header. A key in the query string (?api_key= or ?access_token=) is refused with credentials_in_url: rotate a key that ended up in a URL.
• Only from servers. The API sends no CORS headers, so browsers cannot call it with a key, and a key in front-end code would leak anyway.

To check which key a request uses, call GET /v1/api-keys/whoami: it answers with the key's id, name, scopes and workspace.

OAuth access tokens

Apps that workspaces install from the Kweko marketplace (or privately) get access through OAuth 2.0 with PKCE. The app receives an access token kwk_at_… (valid for 1 hour) and a refresh token kwk_rt_… (valid for 60 days), bound to one installation in one workspace, and sends the access token exactly like a key:

curl https://api.kweko.uz/v1/leads \
  -H "Authorization: Bearer kwk_at_…"

The token carries the scopes the workspace granted to the app. Apps share the workspace's API rate limit with its keys. The full flow is in OAuth for apps.

Errors