Keys and modes
Every request carries an API key as a Bearer token in the Authorization header. The key decides which account the request acts for, whether it sees test or live data, and what it may do.
Pick the kind of key
| Kind | Starts with | Use it for |
|---|---|---|
| Secret | kashu_sk_test_ or kashu_sk_live_ |
Your server. It can call every endpoint in its mode. |
| Restricted | kashu_rk_test_ or kashu_rk_live_ |
A server or tool that needs only part of the API. It holds a list of scopes. |
| Publishable | kashu_pk_test_ or kashu_pk_live_ |
The buyer's browser. It works only on the card form's endpoints, and only on the origins it lists. |
Keep secret and restricted keys on your server. A publishable key is safe in a web page.
Test mode and live mode
A key's prefix names its mode. A test key reads and writes only test data, and a live key only live data. An id from one mode answers 404 resource_missing in the other. Every object carries livemode, so you can tell which mode made it. Test payments never charge a real card.
Live mode is not available yet. Until it is, every request with a live key answers 403 livemode_unavailable.
Get your first keys
Kashu turns on API access for your account and sends you a test secret key and a test publishable key. To ask for them, write to help@kashupay.com. After that, you make and manage keys yourself with the API keys endpoints.
GET /v1/account tells you which account a key belongs to, its mode, the API version the key answers in, and your default store.
Make a key
This makes a restricted key for a tool that reads payments and makes refunds:
curl https://api.kashupay.com/v1/api_keys \
-H "Authorization: Bearer $KASHU_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"restricted","scopes":["payments:read","refunds:write"],"label":"Refund tool"}'The response's token is the key. For a secret or restricted key, the token appears only in this response, because Kashu keeps only a hash of it. Reads and lists show display instead, such as kashu_sk_test_4eC3...0aaa. A publishable key's token shows in every response.
A key is made in the mode of the key that makes it. A key can make only a key with no more access than its own: a secret key can make any key, and a restricted key only a restricted key whose scopes it holds itself.
Give a restricted key its scopes
A scope is <resource>:read or <resource>:write, and write includes read. A request outside the key's scopes answers 403 insufficient_scope. These are the scopes:
| Resource | Scopes |
|---|---|
| account | account:read |
| api_keys | api_keys:read, api_keys:write |
| card_tokens | card_tokens:write |
| checkout_sessions | checkout_sessions:read, checkout_sessions:write |
| customers | customers:read, customers:write |
| disputes | disputes:read, disputes:write |
| events | events:read, events:write |
| payment_methods | payment_methods:read, payment_methods:write |
| payments | payments:read, payments:write |
| refunds | refunds:read, refunds:write |
| subscriptions | subscriptions:read, subscriptions:write |
| webhook_endpoints | webhook_endpoints:read, webhook_endpoints:write |
Roll a key
Roll a key to replace its token without changing what it can do. POST /v1/api_keys/{id}/roll returns a new key with the same kind, scopes, label, API version and allowed origins. The old key stops at once, unless you send expires_in: then it keeps working for that many seconds, up to 604800 (7 days), so you can deploy the new key first.
Revoke a key
POST /v1/api_keys/{id}/revoke stops a key at once. A request with a revoked key answers 401 api_key_expired.
Set a publishable key's origins
A publishable key lists the origins the card form may appear on, in allowed_origins, when you make it:
curl https://api.kashupay.com/v1/api_keys \
-H "Authorization: Bearer $KASHU_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"publishable","allowed_origins":["https://shop.example.com"]}'An origin is a scheme, host and port, with no path, such as https://shop.example.com or https://shop.example.com:8443. A key lists up to 20. A live key lists https origins only. A test key may also list http://localhost or http://127.0.0.1, with a port, while you build. The form refuses to load anywhere else.
You cannot change a key's origins. To add one, make a new publishable key with the full list, deploy it, then revoke the old key.