Skip to content
LogoLogo

Integrations

Provider catalog metadata and live external entities linked to Assign resources.

List Assign integration providers

GET/api/v1/integration-catalog

Returns the bounded, server-owned provider catalog. Availability describes product readiness; it does not imply that the current Workspace has installed or authorized a provider.

Responses

List current Workspace integration installations

GET/api/v1/workspaces/{workspace_id}/integration-installations

Returns a display-safe, persisted-only projection of current provider installations for the session Workspace. The operation never calls a provider and excludes credentials, external tenant identifiers, grants, provider metadata, personal connections, and disconnected history.

Path Parameters

workspace_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Query Parameters

cursor
string·min 1·max 2048

Opaque continuation cursor returned by the preceding page.

limit
integer·min 1·max 100·default 20

Maximum current installations to return.

Header Parameters

X-Assign-Realtime-Baseline
string

Upcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.

Values
1

Responses

Begin an installation or personal provider authorization

POST/api/v1/workspaces/{workspace_id}/integration-authorizations

Creates a ten-minute single-use state and a provider authorization ceremony, using PKCE S256 when supported or confidential client authentication when required by the provider. Owners/Admins may create Workspace installation authority; every member may authorize only their own delegated identity inside an existing installation. Secret material and PKCE verifiers are never returned.

Path Parameters

workspace_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Request Body

application/json
provider_keyRequired
string·min 2·max 50
authority_modeRequired
string
Values
installationuser
installation_id
string <uuid>

Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.

Example0198ac5e-f9b7-7000-8000-000000000001
return_pathRequired
string·min 1·max 1024
gitlab_self_managed
object

Required only when creating a new GitLab Self-Managed installation. Reconnects reuse the installation's vault-backed configuration.

Responses

Enroll an outbound private-network integration connector

POST/api/v1/workspaces/{workspace_id}/integration-private-connectors

Creates a Workspace-scoped connector identity and returns its bearer token exactly once. Owners/Admins must transfer the token directly into the connector process; Assign never returns it again.

Path Parameters

workspace_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Request Body

application/json
display_nameRequired
string·min 1·max 160

Responses

Complete a provider authorization with a user-supplied credential

POST/api/v1/workspaces/{workspace_id}/integration-authorizations/credential

Claims the matching unexpired installation state for the same signed-in Workspace actor, validates the credential directly with a provider that has no scoped OAuth flow, stores it in the approved vault, and persists only opaque references. The credential is accepted only in this authenticated JSON body and is never returned, placed in a URL, or written to browser storage. Replay and cross-actor completion are rejected.

Path Parameters

workspace_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Request Body

application/json
stateRequired
string·min 32·max 256
credentialRequired
string·min 16·max 256

Provider credential submitted only to the authenticated completion endpoint. Clients must not persist, log, or place this value in a URL.

Responses

Complete a provider authorization callback

GET/api/v1/integration-authorizations/callback

Claims one unexpired authorization attempt, exchanges an OAuth code with the provider's accepted PKCE or confidential-client flow or verifies a provider-native installation callback, stores credentials in the approved vault, persists only opaque references, and redirects to the bound Assign return path. Standard OAuth and GitHub App callbacks carry the one-use query state. A Sentry App post-install callback carries code, installationId, and orgSlug and is bound to the initiating browser by a short-lived, callback-scoped HttpOnly Secure SameSite=Lax cookie. Replay is rejected.

Query Parameters

state
string·min 32·max 256

One-use authorization state. Required for standard OAuth and GitHub App callbacks; omitted only by a Sentry App post-install callback, which uses the callback-scoped browser cookie established by the authenticated start operation.

code
string·min 1·max 4096

OAuth authorization code. Required for OAuth callbacks and omitted by provider-native installation callbacks.

installation_id
string·min 1·max 128

Provider-native installation identifier. Accepted only for the matching installation authorization attempt.

installationId
string·min 1·max 128

Sentry App installation UUID supplied by Sentry's post-install redirect. Accepted only with code and orgSlug for the cookie-bound Sentry authorization attempt.

orgSlug
string·min 1·max 100

Sentry organization slug supplied by Sentry's post-install redirect. Accepted only with code and installationId for the cookie-bound Sentry authorization attempt.

setup_action
string·min 1·max 32

Provider-native installation outcome passed through to the matching adapter.

Responses

303Redirect to the bound Assign setup page for browser navigation.

List personal integration identities

GET/api/v1/me/integration-identities

Returns a bounded, persisted-only projection of the current User's passive provider identities and derived delegated-authorization state in the session Workspace. The operation never calls a provider and excludes stable remote user identifiers, credential references, granted scopes, provider payloads, other Users, and disconnected identity or installation history.

Query Parameters

cursor
string·min 1·max 2048

Opaque continuation cursor returned by the preceding page.

limit
integer·min 1·max 100·default 20

Maximum personal integration identities to return.

Header Parameters

X-Assign-Realtime-Baseline
string

Upcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.

Values
1

Responses

Disconnect the current User's delegated provider identity

DELETE/api/v1/me/integration-identities/{identity_id}

Revokes only the current User's delegated credential, preserves the Workspace installation and other Users, and records an immutable safe audit event. Local revocation is authoritative if provider revocation is unavailable.

Path Parameters

identity_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

If-MatchRequired
string

Entity tag containing the resource version last observed by the client.

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Responses

Request an integration provider

POST/api/v1/workspaces/{workspace_id}/integration-requests

Records explicit Marketplace product demand for the session Workspace. The requesting Actor is derived from the authenticated session. The operation performs no provider call and creates no installation, credential, grant, binding, or notification. Repeating a normalized provider name as the same Actor returns the same request identifier and updates the submitted display name and newly supplied use case.

Path Parameters

workspace_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Request Body

application/json
provider_nameRequired
string·min 2·max 80

Provider display name after trimming; control characters are rejected.

use_case
string·max 500

Optional short explanation after trimming; whitespace runs are normalized and remaining control characters are rejected.

Responses

Read one current Workspace integration installation

GET/api/v1/integration-installations/{installation_id}

Returns the same display-safe, persisted-only projection as the current Workspace installation collection. The installation must belong to the session Workspace and must not be disconnected. The operation never calls a provider and excludes credentials, external tenant identifiers, grants, provider metadata, personal connections, and raw provider state.

Path Parameters

installation_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-Assign-Realtime-Baseline
string

Upcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.

Values
1

Responses

Disconnect an integration installation

DELETE/api/v1/integration-installations/{installation_id}

Owners/Admins stop new provider work, revoke local credential references, disconnect resources/bindings, disable subscriptions, and preserve historical links and safe audit. Canonical Assign work is never deleted.

Path Parameters

installation_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

If-MatchRequired
string

Entity tag containing the resource version last observed by the client.

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Responses

List persisted remote resources

GET/api/v1/integration-installations/{installation_id}/resources

Path Parameters

installation_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Query Parameters

limit
integer·min 1·max 100·default 20

Header Parameters

X-Assign-Realtime-Baseline
string

Upcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.

Values
1

Responses

Create a provider installation-management handoff

POST/api/v1/integration-installations/{installation_id}/management-link

Owners/Admins request a fresh provider-owned settings URL for one active Workspace installation. The provider call occurs outside the database transaction. The response contains only the validated URL and a bounded, display-safe snapshot of current repository selection and granted permission levels; it never exposes credentials or raw provider metadata. Providers without a management surface return provider_capability_unavailable.

Path Parameters

installation_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Responses

Refresh one bounded page of provider resources

POST/api/v1/integration-installations/{installation_id}/resources/refresh

Owners/Admins perform a bounded provider discovery call outside the database transaction; normalized stable resources are then upserted and audited.

Path Parameters

installation_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Query Parameters

cursor
string·max 4096

Header Parameters

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Responses

List current integration bindings for a Project

GET/api/v1/projects/{project_id}/integration-bindings

Returns a cursor-bounded, display-safe, persisted-only projection of current provider installations, remote resources, Project bindings, and aggregate binding-scoped subscription state. The Project must be readable in the session Workspace. The operation never calls a provider and excludes provider-stable resource and tenant identifiers, credential references, scopes, personal identities, raw subscription configuration, provider payloads, and disconnected history. A binding with zero subscriptions is valid and enables no ongoing behavior.

Path Parameters

project_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Query Parameters

cursor
string·min 1·max 2048

Opaque continuation cursor returned by the preceding page.

limit
integer·min 1·max 100·default 20

Maximum Project integration bindings to return.

Header Parameters

X-Assign-Realtime-Baseline
string

Upcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.

Values
1

Responses

Bind a discovered remote resource to a Project

POST/api/v1/projects/{project_id}/integration-bindings

Owners/Admins create or reactivate a binding. Connecting a GitHub repository, GitLab project or Bitbucket repository atomically enables incoming development linkage and queues reconciliation when no development subscription exists. Existing subscriptions, including paused or disabled behavior, are preserved. Task status mappings and provider writeback remain off. Other resources create no implicit ongoing behavior.

Path Parameters

project_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Request Body

application/json
resource_idRequired
string <uuid>

Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.

Example0198ac5e-f9b7-7000-8000-000000000001

Responses

Disconnect a Project integration binding

DELETE/api/v1/integration-bindings/{binding_id}

Owners/Admins disconnect the binding and disable every binding-owned subscription without deleting the remote resource or Project.

Path Parameters

binding_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

If-MatchRequired
string

Entity tag containing the resource version last observed by the client.

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Responses

List configured behavior for one binding

GET/api/v1/integration-bindings/{binding_id}/subscriptions

Path Parameters

binding_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-Assign-Realtime-Baseline
string

Upcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.

Values
1

Responses

Configure explicit ongoing integration behavior

POST/api/v1/integration-bindings/{binding_id}/subscriptions

Owners/Admins configure typed event filters and an explicit direction. All writeback remains off unless the submitted direction and provider-specific capability explicitly enable it.

Path Parameters

binding_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Request Body

application/json
typeRequired
string·min 3·max 100
directionRequired
string
Values
noneincomingoutgoingbidirectional
statusRequired
string
Values
enabledpauseddegradeddisabled
configurationRequired
object

Responses

Verify a Sentry Project binding

POST/api/v1/integration-bindings/{binding_id}/sentry-readiness

Owners/Admins verify the persisted installation, Project binding, enabled behavior, and current provider authorization without creating a Task or changing Sentry.

Path Parameters

binding_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Responses

Update, pause, resume, or disable integration behavior

PATCH/api/v1/integration-subscriptions/{subscription_id}

Path Parameters

subscription_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

If-MatchRequired
string

Entity tag containing the resource version last observed by the client.

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Request Body

application/json
typeRequired
string·min 3·max 100
directionRequired
string
Values
noneincomingoutgoingbidirectional
statusRequired
string
Values
enabledpauseddegradeddisabled
configurationRequired
object

Responses

List typed actions supported by an installation

GET/api/v1/integration-installations/{installation_id}/actions

Returns display metadata, authority and confirmation requirements, binding requirements, and a bounded JSON input schema. It returns no credentials or provider grants. GitHub installations with a current user Gist grant can declare github.gist.import, github.gist.export, and github.gist.link; these are one-shot operations and never create an implicit synchronization subscription.

Path Parameters

installation_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-Assign-Realtime-Baseline
string

Upcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.

Values
1

Responses

Request an idempotent typed remote action

POST/api/v1/integration-actions

Intersects the Actor's integration/work capability, binding, provider grant, declared installation/user authority, confirmation requirement, idempotency fingerprint, and persisted rate budget before durable execution. A github.gist.export input with visibility: secret is invalid unless secret_visibility_ack is exactly secret_gists_are_not_private. Gist actions always use user authority; installation authority cannot substitute.

Header Parameters

X-CSRF-TokenRequired
string·min 43·max 43

Session-bound CSRF token. It must exactly match the __Host-assign_csrf cookie sent with the request.

Idempotency-KeyRequired
string·min 16·max 200

Opaque client-generated key for safely retrying this operation.

Request Body

application/json
installation_idRequired
string <uuid>

Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.

Example0198ac5e-f9b7-7000-8000-000000000001
binding_id
string <uuid>

Opaque Assign-owned UUIDv7 identifier. Clients must not derive meaning from it.

Example0198ac5e-f9b7-7000-8000-000000000001
action_typeRequired
string·min 3·max 100
authority_mode
string
Values
installationuser
confirmedRequired
boolean
inputRequired
object

Action-specific bounded input matching the JSON Schema returned by listIntegrationActionDefinitions. GitHub Gist actions accept only an explicit Gist ID and Markdown filename; import may include project_id/title, export requires document_id/filename/visibility and conditionally the exact secret-Gist acknowledgement, and link requires task_id/gist_id/filename.

Responses

Read durable remote-action status

GET/api/v1/integration-actions/{action_id}

Read after an accepted action, an integrations invalidation, or recovery; reading never repeats the provider action. Results are bounded normalized provider output and never contain credentials.

Path Parameters

action_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Header Parameters

X-Assign-Realtime-Baseline
string

Upcoming browser-session canonical read. Set to '1' to capture the authorized response and a signed Workspace replay cursor in one snapshot. Apply every required retained read before acknowledging a socket checkpoint. Failed or incomplete reads return no cursor.

Values
1

Responses

Verify and durably enqueue a provider webhook

POST/api/v1/webhooks/integrations/{provider_key}/{installation_id}

The provider adapter verifies the raw bounded request before Assign persists only a normalized envelope and digest. Provider delivery identity deduplicates retries. Domain/provider fan-out never occurs before the 202 response.

Path Parameters

provider_keyRequired
string·min 2·max 50
installation_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Request Body

application/json

Responses

Verify and route a provider-global webhook

POST/api/v1/webhooks/integrations/{provider_key}

A configured global provider adapter verifies the bounded raw request before Assign either returns a provider-required synchronous handshake or interaction acknowledgement, completes a matching single-use provider-native authorization, or resolves one active logical installation from a stable remote tenant/resource identifier. Unknown verified updates are acknowledged as ignored; raw bodies and application credentials are never persisted. Discord interaction acknowledgements are returned only after Ed25519 signature verification.

Path Parameters

provider_keyRequired
string·min 2·max 50

Request Body

application/json

Responses

List Sentry-native Assign Project binding options

GET/api/v1/integrations/sentry/options/bindings

Signed Sentry App component callback. Returns at most 20 active bindings matching the installation and Sentry Project; no browser session or customer-entered webhook URL is used.

Query Parameters

installationIdRequired
string·min 1·max 512
projectSlugRequired
string
query
string·max 200

Header Parameters

Sentry-Hook-Signature
string·max 128
Sentry-App-Signature
string·max 128

Responses

List Sentry-native Assign Task options

GET/api/v1/integrations/sentry/options/tasks

Signed Sentry App component callback. Returns at most 20 active Tasks from the explicitly selected Project binding.

Query Parameters

installationIdRequired
string·min 1·max 512
dependentDataRequired
string·min 2·max 2048

JSON object containing the selected binding_id.

query
string·max 200

Header Parameters

Sentry-Hook-Signature
string·max 128
Sentry-App-Signature
string·max 128

Responses

Create and link an Assign Task from Sentry

POST/api/v1/integrations/sentry/issues/create

Signed Sentry issue-link callback. Creates at most one Task per installation, Sentry issue, and bound Assign Project, stores bounded Sentry provenance, and returns the canonical Assign Task link.

Header Parameters

Sentry-Hook-Signature
string·max 128
Sentry-App-Signature
string·max 128

Request Body

application/json
fieldsRequired
object
issueIdRequired
string·min 1·max 1024
installationIdRequired
string·min 1·max 512
webUrlRequired
string <uri>·max 2048
projectRequired
object

Responses

Link a Sentry issue to an Assign Task

POST/api/v1/integrations/sentry/issues/link

Signed Sentry issue-link callback. Links only to an active Task in the explicitly selected Project binding.

Header Parameters

Sentry-Hook-Signature
string·max 128
Sentry-App-Signature
string·max 128

Request Body

application/json
fieldsRequired
object
issueIdRequired
string·min 1·max 1024
installationIdRequired
string·min 1·max 512
webUrlRequired
string <uri>·max 2048
projectRequired
object

Responses

Validate an Assign Sentry alert action

POST/api/v1/integrations/sentry/alert-action

Signed Sentry App callback that accepts the alert action only when its selected binding has an enabled alert-to-Task behavior.

Header Parameters

Sentry-Hook-Signature
string·max 128
Sentry-App-Signature
string·max 128

Request Body

application/json
installationIdRequired
string·min 1·max 512
fieldsRequired
object[]·max 8

Responses

List live external entities linked to a Task

GET/api/v1/tasks/{task_id}/rich-entities

Returns bounded, declarative provider snapshots already persisted by Assign. The read path never fans out to provider APIs. Malformed or unsupported snapshots are omitted, and every external navigation target is an HTTPS URL.

Path Parameters

task_idRequired
string <uuid>
Example0198ac5e-f9b7-7000-8000-000000000001

Query Parameters

cursor
string·min 1·max 2048

Opaque continuation cursor returned by the preceding page.

limit
integer·min 1·max 100·default 20

Maximum Rich Entities to return.

Responses