Developers & Integrations – Off The Rack

Overview

Integration architecture

Off The Rack is a multi-tenant SaaS platform with a NestJS REST API (/api/v1) and a Next.js web app. Tenant data is isolated per organisation; authenticated requests carry a JWT and tenant context.

REST API

JSON over HTTPS. Swagger/OpenAPI served at /api/docs on the API host. Bearer JWT for user-scoped operations.

Implemented (dev)

Microsoft Entra OIDC

PKCE authorization-code flow for interactive sign-in. Group claims mapped to application roles on login.

Implemented (dev)

SAML 2.0 & generic OIDC

SP-initiated SAML and OIDC federation for Okta, Google Workspace, Ping, OneLogin, and generic IdPs.

Planned

SCIM 2.0

Automated user and group provisioning from your IdP into Off The Rack workspaces.

Planned

Disclaimer: Off The Rack is in active development. Capabilities marked Implemented (dev) exist in the codebase and demo environments; Planned items are on the roadmap and may change before release.

REST API

Base URL & versioning

All API routes use the global prefix /api/v1. Configure your integration against the API host for your environment.

Base URL pattern

Production (configure before launch)
https://api.offtherack.app/api/v1

Local development
http://localhost:3001/api/v1

Set otrApiBaseUrl in site-config.js to update the production URL shown on this page.

Tenant context

Multi-tenant requests include tenant scope via the X-Tenant-ID header (UUID) or workspace selection during login. All list and mutation endpoints filter by tenant_id server-side.

Content type

Send Content-Type: application/json on POST, PATCH, and PUT requests. Responses are JSON unless noted (e.g. SAML metadata XML).

Authentication

How to authenticate

Interactive users sign in via Microsoft Entra ID OIDC (PKCE). API calls from the web app and integrations use short-lived JWT access tokens.

Bearer JWT

Primary auth for REST endpoints. Obtain an access token via the Entra OIDC login flow (GET /api/v1/auth/login → callback). Send Authorization: Bearer <token> on each request.

Implemented (dev)

X-Tenant-ID header

Identifies the tenant context when required by the endpoint or gateway. Documented in OpenAPI as an API key scheme.

Implemented (dev)

Refresh tokens

Rotating refresh tokens issued as httpOnly cookies after OIDC callback. Used to obtain new access tokens without re-authenticating.

Implemented (dev)

Machine API keys

Long-lived API keys for server-to-server integrations (ERP, scripts) without an interactive user session.

Planned

Interactive login flow (Entra OIDC)

User opens the web app and selects a workspace.
Browser redirects to GET /api/v1/auth/login?tenant_slug=&workspace_id=.
API generates PKCE state and redirects to Microsoft Entra authorize URL.
After MFA (via your Conditional Access policies), Entra returns an authorization code to GET /api/v1/auth/callback.
API exchanges the code, syncs group membership, maps roles, and returns an access token (plus refresh cookie).

Demo and development builds may also expose a dev login endpoint — disabled in production SSO-enforced workspaces.

Example

Sample API request

List kit requests for a tenant — requires assets:read permission and a valid JWT.

GET /api/v1/kits/requests?status=pending HTTP/1.1
Host: api.offtherack.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…
X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000
Accept: application/json

Example response shape (abbreviated):

{
  "data": [
    {
      "id": "…",
      "name": "Field ENG Camera Kit D",
      "status": "pending",
      "requestedForEmail": "alex.rivera@company.com",
      "requestedForName": "Alex Rivera"
    }
  ],
  "meta": { "total": 1 }
}

See the OpenAPI reference for full request/response schemas, permission requirements, and feature gates (e.g. kits on Business plans).

Webhooks

Outbound event notifications

Off The Rack is designed to support tenant-configured webhooks for inventory, checkout, and procurement events.

Status

The data model includes an integrations table with a webhook type for outbound HTTP callbacks. Event delivery, signing secrets, and retry policies are not yet available for customer configuration.

Planned

Planned event types

Asset created, updated, or retired
Check-out and check-in completed
Kit request approved or fulfilled
Low-stock and reorder threshold crossed
Warranty or lease renewal approaching

Register interest if you need a specific webhook payload — we will prioritise based on enterprise requirements.

Rate limits

Usage limits

Rate limiting protects auth endpoints and shared infrastructure. Limits for production will be published before general availability.

Planned rate limit tiers
Tier	Requests / minute	Notes
Standard API	TBC	Per-tenant sliding window on authenticated routes
Auth endpoints	Stricter	Login, callback, and token refresh — abuse protection
Enterprise	Custom	Higher limits and dedicated capacity on request

Rate limiting is on the security checklist but not yet enforced in all environments. Expect 429 Too Many Requests with Retry-After headers when enabled.

Reference

OpenAPI / Swagger docs

Interactive API documentation is generated from NestJS decorators and served alongside the API.

Documentation URL

https://api.offtherack.app/api/docs

Covers auth, assets, kits, checkouts, warranties, compliance modules, and more. Bearer auth and X-Tenant-ID schemes are documented in Swagger UI.

Implemented (dev)

A public, versioned OpenAPI JSON export and dedicated developer portal are planned for post-launch — this page will link to them when available.

Single sign-on

Enterprise SSO overview

Off The Rack supports federated sign-in so your users authenticate with your existing identity provider — no separate passwords for production tenants when SSO is enforced.

Enforced SSO

Workspace setting blocks password and dev login when enabled — all users must authenticate via the configured IdP.

Planned UI

Break-glass access

Emergency admin accounts bypass SSO via a separate path with enhanced audit logging.

Planned

Domain verification

DNS TXT verification to restrict sign-in to verified email domains and enable enforced SSO.

Planned

Protocols

Supported protocols & identity providers

Configuration templates are planned for common enterprise IdPs. Microsoft Entra OIDC is implemented in the current development build.

Identity provider protocol support
Provider	OIDC	SAML 2.0	Status
Microsoft Entra ID	Yes	Yes	OIDC implemented
Okta	Yes	Yes	Planned
Google Workspace	Yes	Yes	Planned
Ping Identity	—	Yes	Planned
OneLogin	—	Yes	Planned
Generic SAML / OIDC	Yes	Yes	Planned

Setup

IdP configuration steps

High-level steps for IT administrators. Replace <your-domain> with your Off The Rack tenant host.

Microsoft Entra ID (OIDC) — implemented

In Entra ID → App registrations → New registration.
Set redirect URI: https://<your-domain>/api/v1/auth/callback (or the workspace-specific OIDC callback path your tenant uses).
Enable ID tokens; create a client secret in the Azure portal.
In Off The Rack admin: Settings → Identity → OIDC — enter Client ID, secret (stored as vault reference), and tenant ID.
PKCE is enabled by default for the authorization-code flow.

Implemented (dev)

Microsoft Entra ID (SAML 2.0) — planned

Create an Enterprise application → Single sign-on → SAML.
Upload Off The Rack SP metadata from GET /api/v1/identity/sso/saml/metadata?tenant=<slug>.
Download IdP metadata XML → upload via Settings → Identity → SAML.
Configure group claims for role mapping.

Planned

Okta — planned

OIDC: Create a Web application with authorization code + PKCE; use the same callback URL pattern as Entra.

SAML: Use the Okta SAML 2.0 template; paste SP Entity ID and ACS URL from the Off The Rack metadata endpoint.

Planned

Google Workspace — planned

OIDC: Google Cloud Console → OAuth client (Web) with authorized redirect URIs.

SAML: Admin console → Apps → Web and mobile apps → Add custom SAML app.

Planned

Mapping

Attribute & role mapping

Off The Rack maps identity provider attributes to users and application roles on each sign-in.

Identity attribute mapping
IdP claim / attribute	Off The Rack field	Notes
`email` / NameID	`users.email`	Primary user identifier; normalised to lowercase
`oid` / `sub`	`users.entra_object_id`	External object ID for JIT provisioning
`groups` / group claims	`user_entra_groups`	Graph fallback when token group overage occurs
Group → role rules	`entra_group_role_mappings`	Admin-configured mapping to app roles (admin, manager, technician, viewer)

When Entra cannot embed all group IDs in the ID token, Off The Rack detects _claim_names.groups and calls Microsoft Graph GET /me/memberOf to resolve membership before role mapping.

SCIM

SCIM 2.0 provisioning

Automated user and group lifecycle from Entra ID, Okta, or other SCIM-capable IdPs.

Planned configuration

Settings → Identity → SCIM → Generate bearer token (hashed at rest).
In your IdP provisioner, set base URL: https://<your-domain>/api/v1/scim/v2
Auth: Authorization: Bearer <scim-token>
Supported resources: Users and Groups (create, patch, delete).
User delete triggers deactivation (isActive=false) — not hard delete.

Planned

SCIM endpoint summary
Method	Path	Purpose
GET, POST	`/scim/v2/Users`	List / create users
GET, PATCH, DELETE	`/scim/v2/Users/:id`	Read / update / deprovision
GET, POST	`/scim/v2/Groups`	Group sync
GET, PATCH	`/scim/v2/Groups/:id`	Group membership

Enterprise

Enterprise SSO & integration onboarding

SAML/OIDC federation, SCIM, custom rate limits, and dedicated API support are included in Enterprise plans. Our team can walk through IdP metadata exchange, attribute mapping, and pilot tenant setup.

Contact us to schedule an identity workshop or API integration review:

support@orangejuiceapplications.com

Email enterprise team Register interest Contact form

Set otrEnterpriseContactEmail in site-config.js for a dedicated integrations inbox.