> 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/rsa-key-pair.md).

# RSA key-pair

With this method, your system authenticates with a private key JWT: it creates a JWT, signs it with its private RSA key, and exchanges it for an access token. Pactum validates the JWT with your public key. No shared secret is stored on either side.

## Before you start

You need:

* **An RSA key pair.** A private key that you keep secret, and a public key.
* **Your public key registered with Pactum.** Send it to your Pactum contact.
* **The ability to create and sign JWTs** in your application.
* **From Pactum:**
  * Your region's API host
  * Your client ID
  * Your audience (the Auth0 tenant URL for your region)

## 1. Generate an RSA key pair

Generate a new key pair just for the Price Lists API. Don't reuse a key pair from another service.

* The key must be at least 2048 and at most 4096 bits.
* The public key must be in PEM format, optionally inside an X.509 certificate in PEM format.

We recommend generating a 2048-bit key with OpenSSL.

**Generate the private key.** Keep this file secure and never share it, not even with Pactum.

```bash
openssl genrsa -out pactum_api_private.pem 2048
```

**Extract the public key.** This creates a separate file with only the public key, which is safe to share.

```bash
openssl rsa -in pactum_api_private.pem -outform PEM -pubout -out pactum_api_public.pem
```

`pactum_api_public.pem` looks like this:

```
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82
mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm
...
+wIDAQAB
-----END PUBLIC KEY-----
```

Store both PEM files securely.

## 2. Share your public key with Pactum

Send the public key file (`pactum_api_public.pem`) to your Pactum contact. Pactum uses it to verify the JWTs your system sends, and gives you your client ID.

## 3. Build the client assertion

The client assertion is a JWT that your system creates and signs with its private key.

**Header**

* `alg`: the signing algorithm. Must be `RS256`.

**Payload**

| Claim | Value                                                                                                                                               |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iss` | Your client ID.                                                                                                                                     |
| `sub` | Your client ID.                                                                                                                                     |
| `aud` | The audience Pactum gave you: `https://pactum.auth0.com/` (US) or `https://pactum.eu.auth0.com/` (EU).                                              |
| `iat` | When the token was issued (Unix time). Optional, but recommended.                                                                                   |
| `exp` | When the token expires (Unix time). The assertion is single-use: set a very short expiry, such as 60 seconds after `iat`. The maximum is 5 minutes. |
| `jti` | A unique ID for this token, such as a UUID. It prevents replay attacks.                                                                             |

**Limits**

* The whole assertion can be at most 2048 bytes.
* `iss`, `sub` and `aud` can be at most 64 characters each; `alg` at most 16.

Use an established library to create and sign the JWT; writing this yourself is error-prone. [JWT.io](https://jwt.io/libraries) lists libraries for many languages.

**Example (Node.js with `jose`)**

```javascript
const { SignJWT } = require('jose')
const crypto = require('crypto')

async function buildClientAssertion(privateKeyPem, clientId, audience) {
  const privateKey = crypto.createPrivateKey(privateKeyPem)
  return new SignJWT({})
    .setProtectedHeader({ alg: 'RS256' })
    .setIssuedAt()
    .setIssuer(clientId)
    .setSubject(clientId)
    .setAudience(audience)
    .setExpirationTime('1m')
    .setJti(crypto.randomUUID())
    .sign(privateKey)
}

// Load the private key from your secrets store, never from source code.
```

**Example decoded payload**

```json
{
  "iat": 1717079478,
  "iss": "your-client-id",
  "sub": "your-client-id",
  "aud": "https://pactum.auth0.com/",
  "exp": 1717079538,
  "jti": "222ce804-a4bc-40e4-b62f-e2d50f6ee826"
}
```

## 4. Exchange the assertion for an access token

Send the signed assertion to the token endpoint.

**Request**

* Method: `POST`
* Endpoint: `{API host}/auth/v1/oauth/token`
* Header: `Content-Type: application/x-www-form-urlencoded`
* Body (form-urlencoded):
  * `grant_type`: `client_credentials`
  * `client_assertion_type`: `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
  * `client_assertion`: the signed JWT from step 3

**Example (cURL)**

```bash
PACTUM_API_BASE_URL="https://direct-procurement.pactum.com"   # EU: https://direct-procurement.eu-pactum.com
CLIENT_ASSERTION="your_signed_jwt_assertion"

curl --request POST "$PACTUM_API_BASE_URL/auth/v1/oauth/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode "client_assertion=$CLIENT_ASSERTION"
```

**Example response**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "scope": "auth:external-api-client",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

Use the `access_token` on every API call, as described in [Calling the API with an access token](https://docs.eu-pactum.com/price-lists-api/authentication.md#calling-the-api-with-an-access-token).
