Integrations

PurpletGo connects to identity providers, HRIS platforms, and collaboration tools to automate access revocation during offboarding. This page covers the generic integration record API at /api/integrations - it's session-authenticated (your dashboard login, not an API key) and restricted to members with the integrations_manage permission (Super Admin only by default) for anything that creates, changes, or removes a connection.

For webhook-based event delivery, see Webhooks.

Supported integration categories

Integration record

Records are stored per-org, one per service_name. For callers who may manage integrations, the list response masks secret fields in config; everyone else gets config: null (see List integrations):

{
  "id": "3f1b2c4a-9e2b-4a3f-8c1d-2b7e9f0a1c3d",
  "org_id": "...",
  "service_name": "Okta",
  "connection_status": true,
  "config": { "domain": "acme.okta.com", "apiToken": "••••••••" },
  "last_sync": "2025-06-26T06:00:00.000Z",
  "created_at": "2025-01-10T09:00:00.000Z"
}

There's no status enum (connected/degraded/pending), capabilities list, or health-check object - connection_status is a plain boolean, and whether the integration is actually working is inferred from last_sync and whether recent syncs have errored, not exposed as a structured field.

Endpoints

List integrations

GET /api/integrations

Returns every integration record configured for the org. Available to any authenticated user in the org (the offboarding wizard uses it to offer revocation targets), but what you get back depends on your permission:

• With integrations_manage (Super Admin by default): the full record, with secret config fields masked as "••••••••".
• Everyone else: id, service_name, connection_status, last_sync, created_at, and config: null - except for a generic SCIM revocation target, which comes back as config: { "scim": true }.

Response 200 OK (as a non-manager)

[
  { "id": "3f1b2c4a-...", "service_name": "Okta", "connection_status": true, "config": null, "last_sync": "2025-06-26T06:00:00.000Z", "created_at": "2025-01-10T09:00:00.000Z" },
  { "id": "9e1c2f3a-...", "service_name": "GitHub", "connection_status": true, "config": null, "last_sync": "2025-06-26T06:00:00.000Z", "created_at": "2025-02-01T09:00:00.000Z" }
]

Create or update a generic integration

POST /api/integrations

Requires integrations_manage and a step-up (428 without one). Upserts on (org_id, service_name) - posting the same service_name twice updates the existing record rather than creating a duplicate.

{
  "service_name": "Splunk",
  "connection_status": true,
  "config": { "hecUrl": "https://splunk.acme.com:8088", "hecToken": "..." }
}

Response 201 Created - the saved record, with config stripped from the response entirely (not just masked).

Update an integration

PATCH /api/integrations/:id

Requires integrations_manage and a step-up (428 without one). Accepts config and/or connection_status; both are optional and merge-replace rather than partially patch nested config keys.

A few settings have their own audited endpoint and can't be changed here: a config that changes one returns 400 naming that endpoint. Among them are the Microsoft 365 out-of-office reply (auto_reply_enabled, on unless set to false: PATCH /api/integrations/:id/auto-reply-setting) and the Google Workspace Drive transfer to the manager (drive_transfer_enabled, off unless set to true: PATCH /api/integrations/:id/drive-transfer-setting). Both take { "enabled": true } or { "enabled": false }, and a reconnect keeps them.

Disconnect an integration

DELETE /api/integrations/:id

Requires integrations_manage and a step-up (428 without one). Deletes the record. For GitHub and Google Workspace, PurpletGo also makes a best-effort attempt to revoke the stored OAuth token upstream before deleting - if that call fails, the local disconnect still succeeds. Every disconnect is written to the audit log as integration_disconnected.

Response 200 OK - { "success": true }. The response is the same when no record with that id exists in your org: there's no 404, nothing is deleted, and no audit entry is written.

Provider-specific connections

These providers use their own OAuth or connect flow instead of the generic POST /api/integrations above - each writes into the same integration record once connected, but the handshake differs per provider:

The connect routes require integrations_manage (Super Admin by default) and a step-up (428 without one); most are gated behind the plan feature named in the table, but saas-revocation/connect and alumni/connect have no plan gate. Operating an already-connected integration is less strict: azure-ad/sync and hris/sync are open to Admins as well as Super Admins and need no step-up, and GET scim/config (which returns only configured and lastSync) has no role check at all. Most of these are only reachable from the PurpletGo dashboard's OAuth redirect flow rather than being callable as a standalone API for third-party integrators.

SIEM targets aren't integration records: they're managed under /api/siem-targets (GET and POST /, PATCH and DELETE /:id, POST /:id/test, POST /batch-export), session-authenticated, on the Enterprise plan, for members who can manage organisation settings (Super Admins and Admins by default). See SIEM Integration.

A handful of narrower helper endpoints also exist per-provider (status checks, e.g. GET /api/integrations/github/status; cost-tracking, e.g. PATCH /api/integrations/azure-ad/cost; and sync history, e.g. GET /api/integrations/hris/sync-log) - these support the dashboard UI and aren't part of the stable integration API described above.

Related

• Offboarding Initiations - starting offboardings, whose access can then be revoked automatically when the last day ends
• Webhooks - event notifications for offboarding, revocation, asset, checklist and document activity
• Audit Log - integration connect/disconnect and revocation history