> For the complete documentation index, see [llms.txt](https://docs.eu-pactum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eu-pactum.com/price-lists-api/authentication.md).

# Authentication

The Price Lists API uses OAuth 2.0. Your system first gets an access token, then sends it with every API call. This page explains the two ways to get a token.

## Authentication methods

| Method                             | How it works                                                                                                                                        | Best for                                          |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| **Client credentials**             | You exchange a client ID and client secret for an access token. You create the credentials yourself in **Settings → API Clients**.                  | Most integrations. Simple to set up.              |
| **RSA key pair (private key JWT)** | You sign a short-lived JSON Web Token (JWT) with your private RSA key and exchange it for an access token. Pactum verifies it with your public key. | Integrations that must not store a shared secret. |

Both methods are for machine-to-machine use: a backend service calling the API on its own behalf.

### Client credentials

A user who can manage users in your organization creates an API client in **Settings → API Clients** and gets a **client ID** and **client secret**. Your system sends them to the token endpoint and receives an access token.

{% content-ref url="/pages/9eEK87ge3ybeWlVPr01c" %}
[Client Credentials](https://docs.eu-pactum.com/price-lists-api/authentication/client-credentials.md)
{% endcontent-ref %}

### RSA key pair (private key JWT)

Instead of a static secret, your system creates and signs a JWT with a private key:

1. **Prerequisites.** Generate an RSA key pair of 2048 to 4096 bits. Send the **public key** (PEM format) to your Pactum contact. Pactum gives you a **client ID** and an **audience URL**.
2. **Build a client assertion.** Create a short-lived JWT with your client ID as `iss` and `sub`, the audience URL as `aud`, and a unique `jti`. Sign it with your **private key**.
3. **Exchange it for an access token.** Send the signed JWT to the token endpoint. Pactum checks the signature with your public key.
4. **Call the API** with the access token as a bearer token.

{% content-ref url="/pages/k7aV90ZSCotwxIs1Tah2" %}
[RSA key-pair](https://docs.eu-pactum.com/price-lists-api/authentication/rsa-key-pair.md)
{% endcontent-ref %}

## Token endpoint

Both methods use the same endpoint on your region's API host:

```
POST {API host}/auth/v1/oauth/token
```

## Calling the API with an access token

Send the token in the `Authorization` header of every request:

```
Authorization: Bearer <access_token>
```

```bash
PACTUM_API_BASE_URL="https://direct-procurement.pactum.com"   # US; EU: https://direct-procurement.eu-pactum.com
ACCESS_TOKEN="your_access_token"

curl "$PACTUM_API_BASE_URL/price-lists/v1/workspaces" \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

## Hosts and audiences

| Region | API host                                   | Audience (RSA key pair only)   |
| ------ | ------------------------------------------ | ------------------------------ |
| US     | `https://direct-procurement.pactum.com`    | `https://pactum.auth0.com/`    |
| EU     | `https://direct-procurement.eu-pactum.com` | `https://pactum.eu.auth0.com/` |

Pactum confirms your region and audience during onboarding.

## Security best practices

* **Private key (RSA method).** Store it in a secrets manager, such as HashiCorp Vault, AWS Secrets Manager or Azure Key Vault. Never put it in your codebase or version control. Limit access to the services that need it.
* **Client secret (client credentials method).** Treat it like a password. Never expose it in client-side code or send it over insecure channels.
* **Client assertions (RSA method).** Each one is single-use. Give it a very short expiry, for example 1 minute.
* **Access tokens.** Each token is valid for the number of seconds in `expires_in` (for example 3600, one hour). Store it securely, reuse it until it expires, and request a new one shortly before it does. Don't request a new token for every API call.
* **HTTPS.** Always call the API over HTTPS.

If you have problems authenticating, contact your Pactum representative and include the `Request-Id` header from the failed response.
