# Partner Integration Guide

**Document version:** 1.1
**Last updated:** 2025-12-16

## 1) Overview

The QUBS Integrations API provides partners machine-to-machine access to selected QUBS configuration and reference data.

**This guide covers:**

- How to authenticate (OAuth 2.0 client credentials → JWT bearer token)
- How domain and site access are scoped
- Error handling and recommended integration patterns


## 2) Authentication (OAuth 2.0 client credentials)

All API requests require a valid bearer token (JWT) in the `Authorization` header.

### 3.1 What QUBS provides

During onboarding, QUBS provides:

- `client_id`
- `client_secret`
- The token endpoint URL (typically the QUBS authentication domain)
- Your allowed `domain` value(s) (one or more)


### 3.2 Get an access token

Request a token using OAuth 2.0 Client Credentials.

**HTTP request**

- Method: `POST`
- URL: `https://{AUTH_HOST}/oauth2/token` (QUBS commonly uses `authenticate.qubs.io` for `{AUTH_HOST}`)
- Content-Type: `application/x-www-form-urlencoded`
- Grant type: `client_credentials`


**cURL (client credentials in body)**


```bash
curl -X POST "https://{AUTH_HOST}/oauth2/token" \
  -H "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}"
```

**Typical token response**


```json
{
  "access_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

### 3.3 Call the API with the token

Include the token in every request:


```
Authorization: Bearer {access_token}
Accept: application/json
```

When the token expires, request a new token (client credentials does not use refresh tokens).

## 4) Authorization model (domain and site scoping)

Every endpoint includes a `{domain}` path parameter, and some also include `{siteName}`.

- Your integration is scoped to one or more **domains**.
- Requests to domains you do not have access to are rejected (typically `403 Forbidden`).
- Within an allowed domain, some endpoints also require authorization for a specific site.


**Important:** Treat `domain` and `siteName` as opaque identifiers. Use the values returned by the API. If `siteName` contains spaces or special characters, URL-encode it.

## 5) Content types, formats, and conventions

- Request/response content type: `application/json`
- Error content type (most errors): `application/problem+json`
- Date/time fields are ISO-8601 (RFC 3339) strings, e.g. `2025-12-16T03:04:05.678Z`
- JSON uses `camelCase` property names


## 6) Security, privacy, and data handling

- Treat access tokens as secrets; store them securely and rotate credentials on schedule.
- Do not log full bearer tokens; redact tokens in application logs.


## 7) Support & change management

- For onboarding, credential issues, domain/site access changes, or questions: contact your QUBS integration representative.
- This API is versioned. Backward-incompatible changes will be released under a new version path.