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

# Authentication

> Obtain and use OAuth access tokens for the Partner API

PayEm Partner API uses OAuth 2.0. Exchange your **client ID** and **client secret** for a short-lived access token outside the API Reference.

## Client credentials (recommended for server-to-server)

```bash theme={null}
curl --request POST "https://app.payemcard.com/oauth/token" \
  --user "<client_id>:<client_secret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "scope=PARTNER_API_V1_BASIC PARTNER_API_V1_CARDS"
```

Use `https://stage.payemcard.com/oauth/token` when testing against Staging. Never paste your client secret into the API Reference.

Example response:

```json theme={null}
{
  "access_token": "....",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "PARTNER_API_V1_BASIC PARTNER_API_V1_CARDS"
}
```

## Use the API Reference playground

1. Copy only the `access_token` value from the token response.
2. Open an endpoint in the API Reference and select **Production** or **Staging**.
3. Paste the token into the **Bearer** authentication field.

The playground sends it as `Authorization: Bearer <access_token>`. The token expires after **300 seconds (5 minutes)**, so obtain a new token when it expires.

## Call an API

Pass the token as a Bearer header:

```bash theme={null}
curl "https://app.payemcard.com/api/partner/v1/company" \
  -H "Authorization: Bearer <access_token>"
```

## Scopes

| Scope | Access |
| - | - |
| `PARTNER_API_V1_BASIC` | Read-only access to general resources (users, transactions, company, vendors, subsidiaries) and card reads (list/retrieve) |
| `PARTNER_API_V1_CARDS` | Card writes and actions (create, update, lock, unlock, terminate). Lock/unlock/terminate also require `PARTNER_API_V1_BASIC`. |

Request only the scopes your integration needs.

## Generate a new client secret

A company admin can rotate your credentials in the PayEm app under **Settings → Developer**, by selecting **Rotate secret** on your app.

Your client ID stays the same and a new client secret is shown. Rotation immediately invalidates the previous secret and revokes all active access tokens for your app.

> [!WARNING]
>
> Your integration has brief downtime until it authenticates again with the new secret. Plan rotations for a low-traffic window and update the secret in your integration right away.

## Token lifetime

Access tokens expire in **300 seconds (5 minutes)**. Cache the token and refresh before expiry; do not request a new token on every API call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.