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

# RSA key-pair

Leveraging OAuth 2.0, Pactum allows to authenticate with a Private Key JWT, where the client creates and signs a JWT with its private key. The server then validates the JWT using the client's public key, ensuring the authenticity of the request.

\
Prerequisites for authentication

* Generated RSA key pair
* Public key shared with Pactum team
* Ability to create and sign JWT using private key
* Pactum API base URL, client ID and audience (Auth0 tenant URL) values shared by Pactum team

Steps to authenticate

1. Build the client assertion
2. Exchange the assertion for access token

## Resources

Pactum API base URL

* US: <https://procurement.pactum.com>
* EU: <https://procurement.eu-pactum.com><br>

Auth0 tenant URL (audience)

* US: <https://pactum.auth0.com/>
* EU: <https://pactum.eu.auth0.com/>

## Generate RSA key pair

Note: You should generate a separate key pair for each type of credential usage. For example, do not reuse the same key pairs for both Pactum Public API and some other API authentication.

In order to authenticate with Pactum Public API, you must provide the public key encoded in PEM format. You may provide this as an X.509 certificate encoded in PEM format. Pactum enforces a minimum RSA key size of 2048 bits and a maximum key size of 4096 bits. We recommend using OpenSSL to generate a 2048-bit RSA key pair.

1\. Generate a private key and a public key in PEM. You should safeguard the private key and never share it, not even with Pactum:

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

2\. Extract the public key in PEM format using the following command. This command extracts the public key details so it can be safely shared without revealing the details of the private key:

```bash
openssl rsa -in test_key.pem -outform PEM -pubout -out test_key.pem.pu
```

The example below shows the contents of the test\_key.pem.pub PEM file:

{% code overflow="wrap" %}

```
----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82 mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx +wIDAQAB -----END PUBLIC KEY-----
```

{% endcode %}

3\. Save the PEM files. You will need the contents later.

### Share public key file with Pactum team

In order to authenticate with JWT signed using the private key, Pactum team needs to configure the API using the public key.

Send the public key file (i.e. `test_key.pem.pub`) to your Pactum contact.

## Build the client assertion

The assertion is a JSON Web Token (JWT) that should contain the following properties and claims:

Header

* `alg`: The signing algorithm, e.g., RS256.

Payload

* `iss`: Your application's Client ID.
* `sub`: Your application's Client ID.
* `aud`: The Auth0 tenant URL.
* `iat`: Issued At timestamp (optional).
* `exp`: Expiration timestamp (max 5 minutes). The client assertion is a one-time use token, and we recommend the shortest possible expiry time.
* `jti`: Unique claim ID, preferably a UUID.

This JWT is a one-time use only token and should be considered as such by having a short expiry. We recommend setting a maximum of 1 minute.

The token must then be signed with the private key you generated previously.

We recommend you construct the token using standard tooling or third party libraries that support this functionality out of the box, rather than implementing from scratch yourself. To learn more about supporting libraries, read the listing at[ JWT.io](https://jwt.io/libraries).

### Assertion limits

The maximum length of the JWT assertion is 2048 bytes.

Claims within the assertion have the following limits:

* `iss`: 64 characters
* `sub`: 64 characters
* `jti`: 64 characters
* `alg`: 16 characters

### Example

In the example below, the Node.js script uses a[ jose package](https://github.com/panva/jose) to generate the assertion:

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


async function main() {
 const privateKeyPEM =
   crypto.createPrivateKey(/**
     Read the content of your private key here. We recommend storing your private key in a secure infrastructure.
     */
   );
 const jwt = await new SignJWT({})
   .setProtectedHeader({
     alg: 'RS256',
   })
   .setIssuedAt()
   .setIssuer('CLIENT_ID')
   .setSubject('CLIENT_ID')
   .setAudience('AUTH0_TENANT_URL')
   .setExpirationTime('1m')
   .setJti(uuid.v4())
   .sign(privateKeyPEM);


 return jwt;
}
main().then(console.log).catch(console.error);
```

Example client assertion JWT signed with a private key:

{% code overflow="wrap" %}

```
eyJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE3MTcwNzk0NzgsImlzcyI6Im15IGNsaWVudCBpZCIsInN1YiI6Im15IGNsaWVudCBpZCIsImF1ZCI6Imh0dHBzOi8vcGFjdHVtLmF1dGgwLmNvbS8iLCJleHAiOjE3MTcwNzk1MzgsImp0aSI6IjIyMmNlODA0LWE0YmMtNDBlNC1iNjJmLWUyZDUwZjZlZTgyNiJ9.jAKsp2tWZLEXLmao_AA0KlXW2cRpqvfv2TJwkMPBA5R5uJCgYGTXWqz6xvLcBDnv1ji5oY9tsIR5bfyX1M731ym50btsImupBnw3fISXn3X9puqG5L1eJdDqmdspUxhp8LQ4kS8xKJEkSzouQSKJMuZ4sraSSc-saqCnWmj92X62y8teufp6vtxeFNVRBhMhZaAk4TyYJr79b-iFZ5r8Fhy53nDGLcQwEDxaLLScXhv5erJCRjI8CvAK-5DkVLogl6zywixmnP8puKAQBQcUN7tFq0zIh9NWFUXsahHfZjb1apZrZ3rOZGwoABCc_yBhJkTHDCKjJo2xuj2H3dnIxA
```

{% endcode %}

This corresponds to:

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

After you generate the JWT with the required information, you are ready to authenticate your application against Pactum Public API.

## Exchange the assertion for access token

To exchange the JWT assertion for an access token, call the Authentication API token endpoint with the following parameters:

* `$client_assertion`: JWT assertion
* `$base_url`: Pactum API base URL

Example request with curl:

```bash
curl --location --request POST '$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:

```json5
{
 "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3BhY3R1bS5hdXRoMC5jb20vIiwic3ViIjoieW91cl9lbWFpbEB5b3VyX2RvbWFpbi5jb20iLCJhdWQiOiJodHRwczovL2FwaS5wYWN0dW0uY29tL2FwaS92MSIsImlhdCI6MTcxNjk5NDMzNSwiZXhwIjoxNzE2OTk3OTM1LCJzY29wZSI6ImF1dGg6ZXh0ZXJuYWwtYXBpLWNsaWVudCIsImd0eSI6ImNsaWVudC1jcmVkZW50aWFscyIsImF6cCI6IkJDZnBsQzZQUDczTnI3enNLcWtkYVFUTzcyNFBXTGFSIiwicGVybWlzc2lvbnMiOlsiYXV0aDpleHRlcm5hbC1hcGktY2xpZW50Il19.zeewkrnqe6VHXbDggjBXIeGi-p_LXnY4MEwLt31cCzhViUNsaiyl9njNuthBWN3kaus78ShvJOTAjSV8ijJmFG8QAHESJmZenJxp4fWU3aZvjEXTW6Lqs_ONn-UBNEdmDxNq-p1GjplsyIwTeFaqHdqk34byapDdyc_018tKCGUG_Njt1orGdE6NvzUlgsTsm0l5vzEyogQ5ObD5atkqlvEofMrQ8tQY00AqrbUxrGM3C-re7eeV9i5LqHCzgNjAv9jnxaeBFVQz8JyM73eC4xtfwUNvXM57gH0rTa3r5_xgxMZB9rJqNAYO6frkwo9Fyf3eQAzr4LCY9LZ8yh7CKeQ3Fty2Wrb47MoOrqtHJ1LcgDZDgkLmEHm2hgGDKsYBG-gzFmPtncARRr6wBtO4v223lvypFIuWSW3oZxb2z0ELErWzTwqoGOyWn58IPj5-4o3azNTFMTW_kt4R6icfzYOrgng_GwBN1lwqsyz7t6Ak9CmVfe_NESrb0kpKXVQuTlQOrqkEfPG6VICyRXhjKCDVPr5m8FPKEWyrxbuZfhMcR4_Zqt3QQZxwQQ2x1wGgCCd1050QugZFcV-A2lT7QcYfJcigmKoeX_sbgl3m0MX7wrYSwyRg-hlgSk606RxKhwh6sQhy8uVDHjmb66ZwuHnWpLgZtJOC__4HpFiRcWE",
 "scope": "auth:external-api-client",
 "expires_in": 3600,
 "token_type": "Bearer"
}
```

## Call the API with access token

Call the Pactum API with `Authorization` header using following parameters:

* `$base_url`: Pactum API base URL
* `$access_token`: JWT assertion

Example API call:

```bash
curl --location --request GET '$base_url/procurement/v1/workspaces' \
 --header 'Authorization: Bearer $access_token'
```
