Skip to content
Last updated

QUBS Integrations API (v1) — 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.

Base path (all endpoints): /integrations/v1

This guide covers:

  • How to authenticate (OAuth 2.0 client credentials → JWT bearer token)
  • How domain and site access are scoped
  • Available endpoints, parameters, and response payloads
  • Error handling and recommended integration patterns

2) Environments & base URLs

QUBS will provide your environment hostnames during onboarding.

  • Sandbox: https://{SANDBOX_HOST}
  • Production: https://{PROD_HOST}

All requests must use HTTPS.

3) 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)

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

{
  "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
  • Endpoints are read-only (GET) and safe to retry
  • Pagination is not currently used; list endpoints return full result sets

6) Errors & troubleshooting

6.1 Standard HTTP status codes

  • 200 OK: Success
  • 400 Bad Request: Invalid request (e.g., missing/invalid parameters)
  • 401 Unauthorized: Missing/invalid/expired token
  • 403 Forbidden: Authenticated but not authorized for requested domain/site/action
  • 404 Not Found: Resource not found (applies to some endpoints)
  • 500 Internal Server Error: Unexpected server-side error

6.2 Error body (RFC7807 Problem Details)

Errors are returned as RFC7807 Problem Details.

Example (403 Forbidden):

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "You are not allowed to access this resource.",
  "instance": "/integrations/v1/acme/sites"
}

7) OpenAPI specification

QUBS maintains an OpenAPI document for this API.

  • If you are provided an OpenAPI URL by QUBS, import it into Postman/Insomnia/your client tooling.
  • A static copy may also be supplied as integrations-v1.json.

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

9) Support & change management

  • For onboarding, credential issues, domain/site access changes, or questions: contact your QUBS integration representative.
  • This API is versioned via the URL (/integrations/v1). Backward-incompatible changes will be released under a new version path.
 
Next page