> 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/client-credentials.md).

# Client Credentials

With the client credentials flow, your system authenticates with a `client_id` and `client_secret` and gets an access token. The flow follows [OAuth 2.0 RFC 6749, section 4.4](https://tools.ietf.org/html/rfc6749#section-4.4). Pactum's token service runs on Auth0; see the [Auth0 documentation](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) for background on the flow.

## Before you start

You need:

* Your region's API host (US: `https://direct-procurement.pactum.com`, EU: `https://direct-procurement.eu-pactum.com`).
* A client ID and client secret. You create them yourself, as described below.
* To create them, you must be able to manage users in your organization. Only those users see **API Clients** in **Settings**.

## Create an API client

1. Go to **Settings → API Clients**. The list shows each client's name, environment, client ID, a masked client secret and the workspaces it can access.
2. Click **Add API client**. The **Create New API Client** dialog opens.
3. Fill in:
   * **Client Name**: a descriptive name, ideally the name of the system that will call the API.
   * **Environment**: **Sandbox** or **Production**. The workspace list shows only workspaces of that environment.
   * **Workspace Access**: select the workspaces the client can access. Select at least one.
4. Click **Create Client**.
5. The second step shows the client details and the **Client ID** and **Client Secret**. Copy both and store the secret securely, for example in your company's password manager or secrets store. Then click **Complete Setup**.

{% hint style="warning" %}
You see the full client secret only once. After you leave this step, only the first and last 3 characters are visible.
{% endhint %}

{% hint style="info" %}
Anyone who can manage users can create API credentials. Using the API in production must be agreed with Pactum and may be subject to additional pricing.
{% endhint %}

{% hint style="warning" %}
**SCREENSHOT:** The API Clients list in Settings with the **Add API client** button and one demo client (client secret masked), then the **Create New API Client** dialog with a client name, Environment and Workspace Access filled in. Route: `/<organization>/settings/api-clients` · Use a demo workspace, no real customer or supplier data.
{% endhint %}

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2F3dE60aRPciiAAkpHoIsn%2Fimage.png?alt=media&amp;token=2f740f2a-b87f-4698-9c1f-e9e1ad98ef1f" alt="The Create New API Client dialog"><figcaption></figcaption></figure>

## Manage an API client

In the list, use the actions on each client:

* **Edit**: change the name and which workspaces the client can access.
* **Copy**: create a new client with the same settings. The new client's name ends in "(Copy)".
* **Remove**: delete the client. Calls with its credentials stop working.

## Rotate credentials

To rotate credentials, because of your policy or a leak:

1. Use **Copy** to create a new client with access to the same workspaces.
2. Switch your system to the new client ID and secret.
3. **Remove** the old client so its credentials can't be used any more.

## Get an access token

Send your client ID and secret to the token endpoint.

**Request**

* Method: `POST`
* Endpoint: `{API host}/auth/v1/oauth/token`
* Headers: `Content-Type: application/x-www-form-urlencoded`, and `Accept: application/json` (recommended)
* Body (form-urlencoded):
  * `grant_type`: `client_credentials`
  * `client_id`: your client ID
  * `client_secret`: your client secret

**Example (cURL)**

```bash
PACTUM_API_BASE_URL="https://direct-procurement.pactum.com"   # EU: https://direct-procurement.eu-pactum.com
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"

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_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET"
```

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

```javascript
const axios = require('axios')

async function fetchAccessToken(baseUrl, clientId, clientSecret) {
  const params = new URLSearchParams()
  params.append('grant_type', 'client_credentials')
  params.append('client_id', clientId)
  params.append('client_secret', clientSecret)

  const response = await axios.post(`${baseUrl}/auth/v1/oauth/token`, params, {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Accept: 'application/json',
    },
  })
  return response.data
}

// Keep the client secret out of your code: read it from a secrets store.
fetchAccessToken('https://direct-procurement.pactum.com', process.env.CLIENT_ID, process.env.CLIENT_SECRET)
  .then((tokenInfo) => console.log(tokenInfo.expires_in))
  .catch(console.error)
```

**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).

**Errors**

| Status | `error`               | Meaning                                                                              |
| ------ | --------------------- | ------------------------------------------------------------------------------------ |
| `400`  | `invalid_request`     | The request is malformed.                                                            |
| `401`  | `invalid_client`      | The client ID or secret is wrong.                                                    |
| `403`  | `access_denied`       | The request was denied.                                                              |
| `429`  | `rate_limit_exceeded` | Too many token requests. Wait for the number of seconds in the `Retry-After` header. |
