Authentication
All requests to the Korven One API are authenticated with a bearer token in the Authorization header.
Bearer authentication
API v1
GET /v1/payments HTTP/1.1
Host: api.korvenone.com
Authorization: Bearer sk_live_a1b2c3...
Korven-Version: 2026-04-01
Content-Type: application/jsonThe token is sent as Authorization: Bearer <key>. Basic auth, query-string keys, and unsigned JWTs are not accepted.
Key types
| Field | Type | Description |
|---|---|---|
sk_live_* | secret | Full-privilege server key for production. Never expose to browsers. |
sk_test_* | secret | Full-privilege sandbox key. Safe to share within the team. |
pk_live_* | publishable | Browser-safe key for tokenising cards and initialising checkout. |
pk_test_* | publishable | Sandbox equivalent of the publishable key. |
rk_* | restricted | Scoped key with a subset of permissions (e.g. read-only payments). |
Required headers
| Field | Type | Description |
|---|---|---|
Authorizationreq | string | Bearer + secret key. |
Korven-Version | string | Pins the API version. Defaults to your account version. |
Idempotency-Key | string | Required on all POST/PUT to guarantee safe retries. |
Content-Typereq | string | Always "application/json" for writes. |
Auth errors
| Field | Type | Description |
|---|---|---|
401 unauthorized | error | Missing, malformed, or revoked key. |
403 forbidden | error | Valid key but wrong scope or environment. |
Rotation & security
- Rotate secret keys every 90 days. Both the old and new key stay valid for 24 hours during rotation.
- Use restricted keys for background workers that only need read access.
- Store keys only in environment variables or a managed secrets store.
- Every key emits an event to the audit log on create, use, and revoke.