Authentication
API keys, authorization headers, and secure credential management for Paystack API requests.
Copy linkOverview
The Paystack API uses API keys to identify your integration and decide what each request can do. Send your secret key, or a restricted key, in the Authorization header of every request, using the Bearer scheme.
Copy linkAPI keys
Paystack has three types of API keys. Restricted keys are optional, and you create them on the dashboard.
| Type | Prefix | Description |
|---|---|---|
| Public key | pk_ | Used on the frontend with Paystack Inline and the Mobile SDKs. Public keys can only initiate transactions to your account. |
| Secret key | sk_ | Used on the backend. Calls every endpoint in the API. |
| Restricted key | rk_ | Used on the backend. Calls only the endpoints covered by its scopes. |
You can find your public and secret keys on the Developers overview page of your dashboard. To rotate your keys or create a restricted key, see API keys.
Danger: Don't commit your secret keys to git, or use them in client-side code.
Copy linkAuthorization header format
Authorization headers should be in the following format:
Authorization: Bearer YOUR_SECRET_KEY
Example:
Authorization: Bearer sk_test_r3m3mb3r2pu70nasm1l3
API requests made without authentication fail with the status code 401: Unauthorized. All API requests must be made over HTTPS.
Danger: Don't set
VERIFY_PEERtoFALSE. Ensure your server verifies the SSL connection to Paystack.
Copy linkTest and live modes
Paystack provides two separate environments for integration:
- Test mode: For development and quality assurance. Transactions and API calls here don't involve real money.
- Live mode: For production. Transactions and settlements are real and processed through your live Paystack account.
Each environment has its own set of public and secret keys. Test keys are prefixed with pk_test_ and sk_test_, while live keys are prefixed with pk_live_ and sk_live_.
Info: The test environment aims to closely mirror live behavior, but not all features are available. For example, settlements aren't processed in test mode, and some payment channels are unavailable.
Copy linkIP whitelisting
IP whitelisting is a security feature that allows only specific IP addresses to make API requests using your secret keys. This provides an added layer of security by preventing unauthorized usage of your secret keys from unknown IP addresses.
When IP whitelisting is enabled, Paystack checks the IP address that each secret key request originates from and compares it with your list of whitelisted IP addresses. If the request's IP address is whitelisted, Paystack allows the request. If not, Paystack blocks the request.
The list applies to your secret key and your restricted keys. You can whitelist up to 10 IP addresses for each environment on the API configuration page of your dashboard. Only administrators, or users with permission to manage API keys and webhooks, can change the list. Paystack sends an email to the main owner of the integration when a user updates the whitelisted IPs for your live secret keys.
Info: Only valid public IPv4 addresses are accepted. IPv6 addresses, IP ranges, and private IP addresses aren't supported.
Copy linkScopes
A scope grants a restricted key access to one resource at one level, written as resource:level, for example transactions:read. The read level grants the endpoints that retrieve a resource, and write grants the endpoints that create, update, or delete it. A write scope includes read for the same resource, so transactions:write also grants transactions:read.
| Resource | Levels |
|---|---|
account | read, write |
apple_pay | write |
balance | read |
bank_accounts | read, write |
banks | read, write |
bulk_charges | read, write |
connect | write |
customer_insights | read |
customers | read, write |
direct_debit | read, write |
disputes_refunds | read, write |
metrics | read, write |
payment_pages | read, write |
payment_requests | read, write |
payouts | write |
plans | read, write |
preauthorizations | read, write |
products | read, write |
settlements | read, write |
subaccounts | read, write |
terminals | read, write |
transactions | read, write |
transfers | read, write |
verification | write |
virtual_accounts | read, write |
webhooks | read, write |
Info: The
accountscopes cover your payment session timeout:account:readfor Fetch Payment Session Timeout, andaccount:writefor Update Payment Session Timeout. If you connect to Paystack through a plugin, includeaccount:readin the plugin's restricted key.
Apple Pay domain endpoints use the transactions scopes: transactions:read to list your domains, and transactions:write to register or remove one. The apple_pay, bank_accounts, and metrics scopes don't cover any endpoints yet.
Copy linkRestricted key errors
Paystack checks the key first, then the key's scopes, then the request itself. A request with a missing scope gets a 403 response even if its body is also invalid.
| Status | Meaning |
|---|---|
401 | The key is unknown, malformed, deleted, or expired. The message is Invalid key, the same as for an invalid secret key. |
403 | The key is valid but doesn't have the scope the endpoint requires. Add the scope to the key on the dashboard, or use a key that has it. |
400 | The key has the required scope, but the request is invalid. This is the same validation error a secret key gets. |
A 403 response looks like this:
{
"status": false,
"message": "This restricted key is not permitted to perform this action"
}
Copy linkKey management best practices
- Read keys from environment variables or a secrets manager, not from source code.
- Restrict who can view or manage API keys on your dashboard.