Connector Installation Lifecycle

Every connector follows the same registration, review, and installation path. A connector definition's review status is separate from the installation status of each workspace or brand that connects it.

End-to-end flow

The diagram shows the usual OAuth path. For a connector that does not use OAuth, skip provider authorization and report completion after setup succeeds or fails. Adspire may also fail a pending installation if it is abandoned or its completion report fails.

1. Register and review the connector definition

The developer registers the connector through the Adspire partner portal. A pending definition is visible in the registering developer's workspace. After internal Adspire review approves it, the definition becomes available to users generally. Rejected or pending definitions are not generally available.

Approval concerns the connector definition, not an individual installation. Approval does not install the connector for users automatically.

2. Start a user installation

An authorized user chooses an approved connector and the applicable brand or workspace. Adspire sends an authenticated POST /install request to the connector with tenant context and runtime values such as brand_api_key, adspire_return_url, and adspire_complete_url.

The connector returns an opaque hash identifying this installation. For OAuth, it also returns an auth_url for the user's browser. Adspire records the installation as pending until the connector reports completion.

3. Complete authorization and setup

For OAuth, the user authorizes the connector with the provider. The connector validates OAuth state, exchanges the authorization code, and stores provider credentials securely for that installation. Do not treat OAuth success alone as installation success if required setup or initial synchronization has not completed.

After setup succeeds, the connector sends a signed request to the exact adspire_complete_url supplied during installation:

{
  "hash": "connector-generated-install-id",
  "status": "active",
  "store_url": "https://store.example"
}

If setup fails, report "status": "failed" instead. Completion reporting is idempotent; retry transient failures with bounded backoff. Return the browser to the supplied adspire_return_url without placing provider credentials in the URL.

4. Operate the active installation

Once completion is accepted, the installation becomes active. The connector can then perform the integration's declared work, such as publishing events, synchronizing provider data, receiving webhooks, or serving declared actions. Apply authorization and tenant scoping to every operation; do not use one installation's credentials for another installation.

For integrations that report sync activity, send one summary per sync run to the sync-report endpoint associated with the supplied completion URL (replace its trailing /complete with /sync-report). Sign the request using the same connector authentication as completion reports. Include a unique run_id and reuse it for retries so reporting is idempotent. A sync report records activity; it does not change the installation's active status.

Example:

{
  "hash": "connector-generated-install-id",
  "run_id": "unique-id-for-this-sync",
  "status": "completed",
  "trigger": "resync",
  "counts": {
    "records": 125
  },
  "duration_ms": 8400
}

5. Uninstall

When a user uninstalls the connector, Adspire sends an authenticated POST /uninstall request with the installation identifier and available tenant context. The connector revokes provider access where supported and deletes its own credentials and data for that installation. Uninstall should be idempotent. Adspire manages its own installation record and marks it expired.

Statuses are separate

State	Applies to	Meaning
Pending review	Connector definition	Submitted by a developer; visible only in that developer's workspace while awaiting review.
Approved	Connector definition	Approved and available to users generally.
Rejected	Connector definition	Not approved for general availability; the developer may need to address review feedback before resubmitting.
Pending	User installation	Install started but setup has not yet been reported complete.
Active	User installation	Connector reported successful setup and the installation can be used.
Inactive	User installation	A user or administrator has disabled an active installation; it is not currently available for use.
Failed	User installation	Setup failed or the pending installation expired without completing.
Expired	User installation	User uninstalled the connector; connector-owned credentials should be removed.

For exact routes, payloads, and request signatures, see Connector Registration and HTTP Contract.