Okta Connect API

8 endpoints.

GET /api/communities/{communityId}/okta-connect/channels

Read through the PARTNER API, so it needs no workspace token and keeps working before one has been minted. A community with no workspace answers an empty list rather than an error — "nothing connected yet" is a state, not a failure.

Auth: Bearer JWT required.

Parameters

Responses

DELETE /api/communities/{communityId}/okta-connect/channels/{channelId}

Disconnects the channel (stopping any live gateway session) and deletes it upstream. This exists because EVERY pairing attempt creates a channel, whether or not it ever produces a QR code. Without it, a few failed attempts leave a list of pending entries an admin cannot clear from inside Gurb. Okta Connect's own documentation names this endpoint for exactly that: "clean up stale channels — e.g. old WhatsApp links left 'awaiting scan'". Uses the workspace-scoped token; the partner surface can list and reserve channels but cannot delete them.

Auth: Bearer JWT required.

Parameters

Responses

GET /api/communities/{communityId}/okta-connect/embed/inbox

Returns a URL to put in an <iframe src>. The URL carries an HS256 JWT signed with the embed shared secret, which is minted SERVER-SIDE and never sent to the browser as a secret — anyone holding it could mint an inbox session for any email address. TWO UPSTREAM PRECONDITIONS, neither in this platform's control:

1. OKTA_CONNECT_EMBED_SECRET must be set. The Partner API does not issue it; the operator hands it over out of band. Absent, this route answers 503 OKTA_CONNECT_EMBED_NOT_CONFIGURED.

2. This platform's domain must be in Okta Connect's frame-ancestors allowlist. Measured 2026-08-19 that list was 'self', getokta.io, dev.getokta.io, s.salla.sa and hamlah.on-forge.com. A correct token in an un-allowlisted frame renders a BLANK IFRAME with a console error and a 200 on the wire — a failure that looks like a bug here and is not one.

The response is Cache-Control: no-store: the URL is a bearer credential for its lifetime.

Auth: Bearer JWT required.

Parameters

Responses

POST /api/communities/{communityId}/okta-connect/provision

Idempotent. The workspace is keyed upstream on external_id = the Gurb community id, so a retry after a timeout returns the existing workspace rather than minting a duplicate tenant. The calling admin becomes the workspace owner upstream. Gurb has no community-owner concept to borrow, and this caller necessarily holds okta_connect:access, which only COMMUNITY_ADMIN is granted.

Auth: Bearer JWT required.

Parameters

Responses

POST /api/communities/{communityId}/okta-connect/sso

The URL is single-use and expires in 300 seconds. It is RETURNED rather than redirected to, because a 302 would burn the ticket on any client that pre-fetches links. Provisions the workspace first if it does not exist yet.

Auth: Bearer JWT required.

Parameters

Request body — application/json

Responses

GET /api/communities/{communityId}/okta-connect/status

Reads Gurb's own record only — no upstream call. Status must stay fast and must not fail when Okta Connect is down.

Auth: Bearer JWT required.

Parameters

Responses

POST /api/communities/{communityId}/okta-connect/whatsapp/qr

Provisions the workspace if needed, mints a workspace-scoped token if needed, then asks Okta Connect to create the channel and boot a pairing session. Poll the status route every few seconds until pending is false. The workspace token never reaches the browser: this endpoint exists so that a credential able to read every conversation in the workspace stays on the server. The client only ever sees the QR string.

Auth: Bearer JWT required.

Parameters

Request body — application/json

Responses

GET /api/communities/{communityId}/okta-connect/whatsapp/qr/{sessionId}

Poll every ~3 seconds while pending is true. The QR payload rotates, so re-render it on every response. Stop as soon as pending is false — connected is success, and failed, qr_expired, disconnected and rate_limited are terminal too.

Auth: Bearer JWT required.

Parameters

Responses