Get started
Authentication
Authenticate API requests with secret keys, keep test and live data apart, and rotate keys without downtime.
Every request to the International Orders API is authenticated with a secret key. Keys identify your account and decide whether a request runs against test data or live data.
This is preview documentation for a prototype. Endpoints, fields and keys are illustrative.
Key types
You get two pairs of keys when you create an account. Find them in the dashboard under Developers → API keys.
| Key | Prefix | Where to use it |
|---|---|---|
| Secret test key | sk_test_ | Your server, in development and CI |
| Secret live key | sk_live_ | Your server, in production only |
| Publishable test key | pk_test_ | The browser, with Checkout Components |
| Publishable live key | pk_live_ | The browser, in production |
Secret keys can move money. Keep them on your server, in an environment variable or a secrets manager. Never put them in client code, mobile apps or a public repository.
Publishable keys are safe to expose. They can only create the browser side of a checkout and cannot read or change your data.
Send your key
The API uses HTTP basic auth. Pass your secret key as the username and leave the password empty. The trailing colon in the example below tells curl there is no password.
curl https://api.international-orders.com/v1/orders \
-u sk_test_51Hx...:
If you prefer a header, send the same credentials as a bearer token:
curl https://api.international-orders.com/v1/orders \
-H "Authorization: Bearer sk_test_51Hx..."
The server SDKs read the key once, when you create the client:
import { InternationalOrders } from "@international-orders/node";
const io = new InternationalOrders(process.env.IO_SECRET_KEY!);
All requests must use HTTPS. Requests over plain HTTP, or without a key, return 401 Unauthorized.
Test mode and live mode
The key you send decides the mode. Objects created with a test key exist only in test mode, and a live key cannot see them. This keeps your experiments out of your books.
Test mode behaves like live mode, with two differences: no money moves, and you can trigger specific outcomes with test cards and scenarios.
Restricted keys
For services that only need part of the API, such as a reporting job, create a restricted key. You choose read or write access per resource, for example read-only access to orders and payouts. Restricted keys start with rk_test_ or rk_live_.
A request outside a restricted key's permissions returns 403 Forbidden with the code permission_denied. See Errors.
Rotate a key
Rotate a secret key if it may have been exposed, or on a regular schedule.
- In the dashboard, choose Roll key next to the key.
- Pick how long the old key should keep working, from immediately to seven days.
- Deploy the new key to your servers.
- Watch the key's last-used time drop to zero, then let the old key expire.
Rolling a key does not affect webhook signing secrets. Those rotate separately in Webhooks.