Manage your API keys to authenticate requests with Smartpay.
The Smartpay API uses API keys to authenticate requests. You can view and manage your API keys in the Smartpay dashboard. If you don’t include your key when making an API request, or use an incorrect or outdated one, Smartpay returns a 401 unauthorized.
Test and live modes
All Smartpay API requests occur in either test or live mode. API objects in one mode (checkout sessions, orders, etc) aren’t accessible to the other.
| Type | When to use | Objects | How to use |
|---|---|---|---|
| Test mode | Use this mode as you build your app. Payments are not processed. | API calls return simulated orders, payments, refunds, coupons, etcetera. | Use test shopper accounts with test credit cards or payment methods. |
| Live mode | Use this mode when you’re ready to launch your app. All payments will be processed. | API calls return actual orders, payments, refunds, coupons, etcetera. | Use valid shopper accounts with real credit cards or payment methods. |
API keys
All accounts have a total of four keys: a public and secret key pair for both test and live mode. Smartpay APIs use your secret key to authenticate requests on your server. By default, your account’s secret keys can be used to perform any API request without restriction. You can find your keys on the Credentials page in the Smartpay Dashboard.
| Type | Value | When to use |
|---|---|---|
| Public | pk_test_PCLEGPw9RrKIAlRcK504Bj |
On the client-side. Can be publicly-accessible in your web or mobile app’s client-side code (such as checkout). |
| Secret | sk_test_Ho1BrYTcg3gAX4vTKk1taz |
On the server-side. Must be secret and stored securely in your web or mobile app’s server-side code (such as in an environment variable or secret manager) to call Smartpay APIs. |
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.
Authentication schemes
Authentication to the API is performed via either HTTP Basic Auth or Bearer Auth:
- HTTP Basic Auth: provide your API key as the basic auth username value. You do not need to provide a password. Example:
-u sk_test_Ho1BrYTcg3gAX4vTKk1taz - Bearer Auth: this might be required for specific situations (e.g. when you need to do a cross-origin request). Example:
-H "Authorization: Bearer sk_test_Ho1BrYTcg3gAX4vTKk1taz"
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Keeping your keys safe
Your secret API key can be used to make any API call on behalf of your account, such as creating orders or performing refunds. Treat your secret API key as you would any other password. Grant access only to those who need it. Ensure it is kept out of any version control system you may be using. Control access to your key using a password manager or secrets management service.