> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paynext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Create and manage scoped API keys with permission-based access control.

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

<Steps>
  <Step title="Open Developers settings">
    In the PayNext Dashboard, go to the **Developers** page and open the **API Keys** tab.
  </Step>

  <Step title="Create a new API key">
    Click **New API key**.
  </Step>

  <Step title="Enter basic details">
    Provide a name for the API key so it is easy to identify later.
  </Step>

  <Step title="Assign permissions">
    Choose the required access level for each resource using the available options:

    * **None**
    * **Read**
    * **Write**
  </Step>

  <Step title="Save the key">
    Click **Create** to generate the API key.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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