Authentication
Send the key as a Bearer token on every request:
Authorization: Bearer ksr_live_3f9a...
A key is ksr_live_ followed by 64 hexadecimal characters; a test key starts with ksr_test_ instead and reaches only the sandbox (see Test mode). Keep it on your server: anyone holding it acts for the merchant.
Permissions
The merchant grants each key a level per resource, written resource:level:
| Permission | Allows |
|---|---|
customers:read | listing and reading customers |
customers:write | the above, plus creating and updating customers |
sales_invoices:read | listing and reading sales invoices, with their PDF and XML |
sales_invoices:write | the above, plus issuing sales invoices |
payments:read | listing and reading payments |
payments:write | the above, plus recording payments |
credit_notes:read | listing and reading credit notes, with their PDF and XML |
credit_notes:write | the above, plus issuing credit notes |
write includes read. A call the key is not allowed to make answers 403 missing_permission, and the error's requiredPermission names the permission it needs. More resources join as the API grows.
Branches
A key may be limited to some of the merchant's branches. A call that names another branch answers 403 branch_not_allowed.
When a key stops working
| Code | Status | Why |
|---|---|---|
missing_api_key | 401 | no Authorization: Bearer header |
invalid_api_key | 401 | the key is malformed or unknown |
revoked_api_key | 401 | the merchant revoked it |
expired_api_key | 401 | its expiry date has passed |
tenant_suspended | 403 | the merchant's Kosoor account is suspended |
None of these is fixed by retrying: ask the merchant for a new key or to restore its account.