Integrations — Reference
The Integrations surface is the third-party connection plane for SGEN. It owns the connection records that pair a site with an external system — Google services, email-service providers, payment platforms, outbound webhooks, analytics tools, CRM destinations. Anything that crosses the boundary from SGEN into another vendor's system traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before scripting against it, scoping a vendor connection, or extending the supported connector library. Customer-facing connection walkthroughs live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Integrations live under the Integrations module in SG-Admin. The module renders four primary views — the connector library, the active-connections list, the per-connection detail view, and the delivery log — and exposes a write surface for connection creation, credential rotation, scope changes, pause and resume, disconnect, and test-connection verification.
A connection is two things stored together: a connector type (the schema for the vendor — what fields the credentials carry, what auth dance is required, what scopes are available) and an active credential record (the per-site values that prove the connection works). The connector type is shared across all sites on the platform; the credential record is per-site and never leaves the site's storage boundary except as opaque tokens to the vendor.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Integrations
- URL prefix:
/sg-admin/integrations/ - View templates:
application/views/Admin/Integrations/
Connection state is observable at the surface. A connection is one of active, paused, auth_expired, auth_revoked, or error. The state drives whether the surface attempts delivery on outbound events and whether the connection appears in pickers across other modules (Forms → integrations, Notifications → channels, Posts → publish destinations).
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Integrations [+ New connection]│├──────────────────────────────────────────────────────────────────────┤│ Connector State Scopes Last delivery ││ ────────────────── ────────────── ────────────── ──────────────││ Google Analytics active read+admin 2 min ago ││ Stripe active payments 11 min ago ││ Mailchimp auth_expired ✗ (re-auth) 2 days ago ││ HubSpot CRM active contacts+deals 34 min ago ││ Brevo (email) paused transactional — ││ Outbound webhook active POST /events now ││ ││ [⋯ View detail] [⋯ Re-auth] [⋯ Test connection] [⋯ Pause] [⋯ Disconnect] │└──────────────────────────────────────────────────────────────────────┘Actions
The Integrations surface exposes the following operations. Each is described by what it does to the data and to the vendor, not by its internal method name.
List and search
Returns the active and historical connections, paginated, with connector name, state, scopes, last-delivery timestamp, and operator-of-record columns. Supports column sort, free-text filter, and state filter (active, paused, auth_expired, auth_revoked, error).
Browse connector library
Returns the catalog of available connector types. Each entry carries the connector name, family, supported auth flows (OAuth, API key, signed-token, basic credentials), supported scopes, and the connection-record shape the connector creates. The library is shared across the platform; new connector types appear here when the platform ships them.
Create connection
Opens the connector-specific create flow. For OAuth connectors, the flow redirects to the vendor's authorization page, returns with an authorization grant, and exchanges the grant for an access record. For API-key connectors, the flow presents a form for the key and any vendor-specific fields. For signed-token connectors, the flow generates the SGEN-side secret and prompts the operator to register it with the vendor.
On completion the surface validates the credential by issuing a low-cost test call to the vendor (typically an account-info or whoami call). A failed validation rejects the connection record; the operator must retry the flow.
Edit connection scopes
For OAuth connectors that support scope changes after connect, opens the scope picker. The picker shows the scopes the vendor exposes for the operator's account and indicates which scopes SGEN currently holds. Submitting a scope change initiates a re-authorization at the vendor — the operator returns to the authorization page, grants the new scope set, and the surface stores the updated access record.
For non-OAuth connectors the action is unavailable; scope is fixed at the credential level.
Refresh credentials
For OAuth connectors that issue access records with a refresh token, the surface holds the refresh token and rotates the access record automatically on expiry. A manual refresh path exists for cases where the vendor invalidates a token out-of-band; the operator triggers the refresh and the surface validates with a test call.
Test connection
Issues a low-cost validation call to the vendor and returns the outcome — connected (with the account or workspace identifier the vendor returned), credential expired, credential revoked, scope insufficient (with the missing scope listed), vendor error (with the error code the vendor returned), or network error. The test never modifies vendor-side state.
Pause connection
Marks the connection as paused. The surface stops attempting deliveries on outbound events and removes the connection from pickers in dependent modules. The credential record is retained. Resume returns the connection to active.
Resume connection
Returns a paused connection to active. The surface re-issues a test call before flipping the state; a failed test leaves the connection in error and the operator must investigate.
Disconnect
Removes the credential record. For OAuth connectors, the surface issues a revocation call to the vendor before removing the local record, so the vendor-side grant is cleaned up. For API-key connectors, the local record is removed without a vendor call — the operator is responsible for rotating the key at the vendor if needed.
A disconnected connection is not retained — re-connecting requires a fresh authorization or key entry. The historical delivery log, however, is retained per the retention period configured under Settings → Integrations.
Browse delivery log
Returns the outbound delivery records for a connection, paginated, with timestamp, originating event (which module triggered the delivery), outcome, vendor response code, and latency columns. Supports column sort, free-text search across event identifiers, date-range filter, and outcome filter (delivered, retried, failed).
Retry failed delivery
For a delivery record on the failure list, re-issues the same call to the vendor. The outcome appends to the delivery log; the original failed entry is retained for audit.
Data model
A connection record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
connector_type | string | The connector slug — google_analytics, stripe, mailchimp, webhook_generic, etc. |
display_name | string | Operator-assigned name. Defaults to the connector display name. |
state | enum | active, paused, auth_expired, auth_revoked, error. |
auth_flow | enum | oauth, api_key, signed_token, basic. |
vendor_account_id | string | The account or workspace identifier the vendor returned. Stable per connection. |
scopes_granted | JSON | Array of scope identifiers currently held. |
credential_blob | encrypted JSON | The access record. Encrypted at rest. Never returned to the surface in cleartext. |
refresh_token_blob | encrypted JSON | OAuth refresh token, when applicable. Encrypted at rest. |
expires_at | timestamp | When the access record expires (nullable for non-expiring credentials). |
last_test_at | timestamp | When the surface last verified the connection. |
last_test_outcome | enum | Mirror of the test-connection result. |
last_delivery_at | timestamp | When an outbound delivery last ran on this connection. |
operator_of_record | integer | The user who initiated the connection. |
created_at | timestamp | Set on connection create, immutable. |
updated_at | timestamp | Touched on credential refresh, scope change, pause, resume. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
connection_id | integer | Foreign key to the connection. |
originating_module | string | Which module triggered the delivery — forms, notifications, posts, etc. |
event_identifier | string | A module-specific identifier — submission id, notification id, post id, etc. |
outcome | enum | delivered, retried, failed. |
vendor_response_code | integer | The response code the vendor returned. Nullable for transport errors. |
latency_ms | integer | Round-trip latency on the call. |
attempted_at | timestamp | When the delivery ran. |
credential_blob and refresh_token_blob fields are encrypted at the database tier with the site-level encryption key. Reads from the surface decrypt only when the credential is actively in use (test call, refresh, outbound delivery) — listing operations never expose the cleartext.Scope semantics: the scopes_granted field is the source of truth for what the connection can do. Dependent modules check scopes_granted before scheduling a call that requires a specific scope. A connection with insufficient scope returns a structured rejection at the call site.
State transitions: the state field is observed-state, not asserted-state. The platform updates it as a side effect of test calls, refresh cycles, and delivery outcomes. The pause and resume actions are the only manual overrides.
INITIAL CREATE│▼[validating]│├──► test passes ──► active│└──► test fails ──► rejected (no record stored)active│├──► refresh succeeds ──► active (timer reset)├──► refresh fails ──► auth_expired├──► vendor revokes grant ──► auth_revoked├──► operator pauses ──► paused├──► delivery error pattern ──► error└──► operator disconnects ──► (record removed)paused ──► resume + test ──► activeauth_expired ──► refresh path ──► activeauth_revoked ──► re-auth flow ──► activeerror ──► test + fix ──► activePermissions
Access to the Integrations surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Integrations surface.
Layer 2 — per-action capability. Within SG-Admin, each Integrations action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List connections | ✔ | ✔ | ✔ |
| Browse connector library | ✔ | ✔ | ✔ |
| Create connection | ✔ | — | — |
| Edit scopes | ✔ | — | — |
| Refresh credentials (manual) | ✔ | — | — |
| Test connection | ✔ | ✔ | — |
| Pause / resume | ✔ | — | — |
| Disconnect | ✔ | — | — |
| Browse delivery log | ✔ | ✔ | — |
| Retry failed delivery | ✔ | ✔ | — |
Credential exposure rules. The surface never returns credential_blob or refresh_token_blob in cleartext to any role. Even Administrator role sees only the connection state, the vendor account identifier, the scopes, and the test outcome. Cleartext access requires a database-tier operation outside the SG-Admin surface.
Connector-family overrides. Some connector families are gated more tightly than the default capability map. Payment-platform connectors (Stripe, PayPal, Square) require an additional capability — manage_payment_credentials — beyond the standard create-connection cap. The capability is held by Administrator by default but can be revoked separately in custom-role configurations.
Audit. Every connection create, scope edit, manual refresh, pause, resume, disconnect, test call, and retry emits an Activity Log entry. The log records the acting operator, the connection identifier, and the outcome. Delivery-log entries are their own audit surface — they are not duplicated to the Activity Log to keep log volume manageable.
OAUTH CONNECTION CREATE│▼┌───────────────────────────┐│ Operator clicks Connect │└─────────────┬─────────────┘│▼┌───────────────────────────┐│ Redirect to vendor auth │ scopes requested└─────────────┬─────────────┘│ operator grants▼┌───────────────────────────┐│ Vendor returns auth grant │└─────────────┬─────────────┘│▼┌───────────────────────────┐│ SGEN exchanges grant │ → access record + refresh token│ for access record │ encrypted at rest└─────────────┬─────────────┘│▼┌───────────────────────────┐│ Test call to vendor │ validates the credential└─────────────┬─────────────┘│ passes▼connection.state = activeActivity Log entryappears in dependent module pickersRelated references
- Settings — Reference. Owns the site-level encryption key configuration, the delivery-log retention period, and the per-connector-family overrides.
- Forms — Reference. Form integrations consume the connection records — a form's routing configuration references a connection by id; the connection state drives whether the form's delivery succeeds.
- Notifications — Reference. Notification channels reference connections (email-service-provider for email, SMS gateway for SMS, webhook destination for outbound events).
- Users — Reference. The Activity Log binds to user records; the operator-of-record on a connection traces back to a user id.
- Webhooks — Reference. Inbound webhooks (vendor → SGEN) are a different surface — they live under Tools → Webhooks. Outbound webhooks (SGEN → vendor) are a connector family here.
- Tools — Reference. Activity Log and the delivery-log search live under Tools.
- Posts — Reference. Posts can publish to social and syndication destinations via connection records.
/docs/integrations.