API keys let you authenticate server-to-server requests to the PayNext API.
PayNext supports scoped API keys, so each key can be limited to specific resources and access levels instead of having full access to the entire platform.
Overview
Scoped API keys help reduce security risk by following the least privilege principle.
With scoped permissions, you can:
- create keys for specific integrations or teams
- allow access only to the resources an integration needs
- separate read access from write access
- limit the impact of a leaked or compromised key
Access to API Key Management
Only the following user roles can access API key settings:
| Role | API key access |
|---|
| Admin | Full access |
| Developer | Full access |
| Other roles | No access |
Permission Model
Permissions are grouped by resource. Each resource supports one of the following access levels:
- None – no access
- Read – read-only access
- Write – write access, including read access where applicable
Permission Groups
Main
| Resource | Available access |
|---|
| Client Sessions | None / Write |
| Customers | None / Read / Write |
| Plans | None / Read |
Payments
| Resource | Available access |
|---|
| Payments | None / Read / Write |
| Refunds | None / Write |
Subscriptions
| Resource | Available access |
|---|
| Subscriptions | None / Read / Write |
| Subscription Cancellation | None / Write |
Endpoint-to-Permission Mapping
Each API request requires a matching permission.
| Method | Endpoint | Required permission |
|---|
POST | /client-session | Client Sessions: Write |
PATCH | /client-session/{id} | Client Sessions: Write |
GET | /customers | Customers: Read |
GET | /customers/{id} | Customers: Read |
POST | /customers | Customers: Write |
PATCH | /customers/{id} | Customers: Write |
GET | /payments | Payments: Read |
GET | /payments/{id} | Payments: Read |
POST | /payments | Payments: Write |
POST | /payments/refund/{id} | Refunds: Write |
GET | /plans | Plans: Read |
GET | /plans/{id} | Plans: Read |
GET | /subscriptions/search | Subscriptions: Read |
GET | /subscriptions/{id} | Subscriptions: Read |
POST | /subscriptions | Subscriptions: Write |
PATCH | /subscriptions | Subscriptions: Write |
POST | /subscriptions/cancel/{id} | Subscription Cancellation: Write |
POST | /subscriptions/schedule-cancel/{id} | Subscription Cancellation: Write |
Create an API Key
Open Developers settings
In the PayNext Dashboard, go to the Developers page and open the API Keys tab.
Create a new API key
Click New API key.
Enter basic details
Provide a name for the API key so it is easy to identify later.
Assign permissions
Choose the required access level for each resource using the available options: Save the key
Click Create to generate the API key.
For security reasons, show the API key value only to the team or system that needs it. Store it in a secure secret manager and avoid sharing it in plain text.
Update an API Key
You can review and update permissions for an existing API key at any time.
Permission changes take effect for subsequent API requests made with that key.
Best Practices
- Create separate API keys per service or integration
- Grant only the minimum required permissions
- Avoid reusing the same key across multiple systems
- Review old keys and remove unnecessary access
- Rotate keys periodically
- Restrict production and sandbox usage to different keys
Notes
Write includes Read where applicable- Some resources support only
Write or only Read, depending on available API operations
- API key management is available only to Admin and Developer roles
