Connector Gateway API: schemas

The request and response bodies of the operations in this API.

AdapterConfigResponseDto

Property	Type	Required
`adapterKey`	string	yes
`configJson`	object	no
`createdAt`	string	yes
`enabled`	boolean	yes
`id`	string	yes
`orgId`	string	yes
`projectId`	string	yes
`updatedAt`	string	yes

AdapterConfigResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of AdapterConfigResponseDto	yes

AdapterConfigResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	AdapterConfigResponseDto	yes

AdapterStatusDto

Property	Type	Required
`configured`	boolean	yes
`effectiveCapabilities`	map of boolean	no
`health`	one of `"NOT_CONFIGURED"`, `"CONFIGURED_UNTESTED"`, `"HEALTHY"`, `"DEGRADED"`, `"MISCONFIGURED"`, `"UNAVAILABLE"`	yes
`lastError`	object or null	no
`operations`	object	no
`provider`	string	no
`refreshMode`	string	no
`sourceOfTruth`	string	no
`supportedCapabilities`	map of boolean	no

AddCredentialsDto

Property	Type	Required	Description
`credentials`	object	yes	Credentials payload. The KEYS are the connector onboarding form’s declared field keys, and they must cover every mint field the connector’s declared CredentialKind reads (see CURATED_CREDENTIAL_KIND_REQUIRED_FIELDS in @xemahq/contracts/connector). Fields declared `isSecret: true` go to credential-broker custody; the rest are stored as non-secret connection configuration and are projected into the minted token’s providerHints.

AppInstallCompleteBodyDto

Property	Type	Required	Description
`installRef`	string	yes	The opaque reference the install callback put on the frontend redirect as `connection_install_ref`. Single use; only the member who started the installation can complete it, and only before the flow expires.

AppInstallCompleteResponseDto

Property	Type	Required	Description
`connectionId`	string	yes	The connection the verified installation is now bound to.
`connector`	string	yes	The connector key the installation was for.

AppInstallCompleteResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	AppInstallCompleteResponseDto	yes

AppInstallLaunchResponseDto

Property	Type	Required	Description
`installUrl`	string	yes	Single-use launch link (on the connector gateway's callback host, valid for two minutes) for the browser to navigate to top-level. It binds the installation to THIS browser with a `__Host-` cookie and redirects to the provider's installation page (the descriptor's `oauthEndpoints.authorizationUrl` templated against the app credential's NON-SECRET config); only this browser can return through the callback. It never contains a secret.

AppInstallLaunchResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	AppInstallLaunchResponseDto	yes

ChangeConnectionEndpointDto

Property	Type	Required	Description
`confirm`	one of `"suspend-credentials"`	yes	Explicit confirmation that every credential on this connection is suspended by the change.
`endpoint`	string	yes	The https origin plus base path the connection talks to. No credentials, query or fragment; the host must be public.
`expectedRevision`	number	yes	The endpoint revision the caller read. A different current revision refuses the change (409).

ChangeConnectionEndpointResultDto

Property	Type	Required	Description
`connectionId`	string	yes
`endpoint`	string	yes
`endpointRevision`	number	yes	The new endpoint revision.
`probe`	ConnectionEndpointProbeDto	yes	Credential-less reachability probe through the guarded transport. A failed probe does not roll the change back.
`suspendedCredentials`	number	yes	Credentials suspended by the change.

ChangeConnectionEndpointResultDtoDataEnvelope

Property	Type	Required	Description
`data`	ChangeConnectionEndpointResultDto	yes

ConfigureAdapterDto

Property	Type	Required	Description
`adapterKey`	one of `"DOCUMENTATION"`, `"TRACKER"`, `"SCM"`, `"NPM_REGISTRY"`, `"CONTAINER_REGISTRY"`, `"MAIL_INTAKE"`, `"MAIL_EGRESS"`, `"CONVERSATION"`	yes	Adapter key
`config`	object	no
`enabled`	boolean	yes

ConnectionDefaultAuthorityErrorCode

CONNECTION_DEFAULT_ORG_ADMIN_REQUIRED: an org-tier default needs an org admin. CONNECTION_DEFAULT_PROJECT_ADMIN_REQUIRED: a project-tier default needs an org admin.

Type: one of "CONNECTION_DEFAULT_ORG_ADMIN_REQUIRED", "CONNECTION_DEFAULT_PROJECT_ADMIN_REQUIRED"

ConnectionDefaultProblemDto

RFC 9457 problem document of a refused default-pointer change. Extension members stay top-level and open.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	ConnectionDefaultAuthorityErrorCode or string	yes	Stable problem code. A `ConnectionDefaultAuthorityErrorCode` on an authority refusal; otherwise the space-registry's code, passed through, or `CONNECTION_DEFAULT_POINTER_NOT_SET`. `CONNECTION_DEFAULT_ORG_ADMIN_REQUIRED`: an org-tier default needs an org admin. `CONNECTION_DEFAULT_PROJECT_ADMIN_REQUIRED`: a project-tier default needs an org admin.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`reason`	DefaultPointerNotSetReason	no	Why the pointer was not authored. Absent on a refusal the gateway decides before asking the registry (`CONNECTION_DEFAULT_*_ADMIN_REQUIRED`).
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ConnectionEndpointBadRequestCode

CONNECTION_ENDPOINT_NOT_APPLICABLE: the connector takes a static base, so its connections carry no endpoint. CONNECTION_ENDPOINT_INVALID: the endpoint failed the shared egress guard. MALFORMED_REQUEST_BODY: the request body is not valid JSON.

Type: one of "CONNECTION_ENDPOINT_NOT_APPLICABLE", "CONNECTION_ENDPOINT_INVALID", "MALFORMED_REQUEST_BODY"

ConnectionEndpointBadRequestProblemDto

RFC 9457 problem document of a 400 from the endpoint change. code is closed.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	ConnectionEndpointBadRequestCode	yes	`CONNECTION_ENDPOINT_NOT_APPLICABLE`: the connector takes a static base, so its connections carry no endpoint. `CONNECTION_ENDPOINT_INVALID`: the endpoint failed the shared egress guard. `MALFORMED_REQUEST_BODY`: the request body is not valid JSON.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ConnectionEndpointConflictCode

CONNECTION_ENDPOINT_REVOKED: a revoked connection is terminal and takes no endpoint. CONNECTION_ENDPOINT_REVISION_STALE: the expected revision is not the current one; re-read and retry.

Type: one of "CONNECTION_ENDPOINT_REVOKED", "CONNECTION_ENDPOINT_REVISION_STALE"

ConnectionEndpointConflictProblemDto

RFC 9457 problem document of a 409 from the endpoint change. code is closed.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	ConnectionEndpointConflictCode	yes	`CONNECTION_ENDPOINT_REVOKED`: a revoked connection is terminal and takes no endpoint. `CONNECTION_ENDPOINT_REVISION_STALE`: the expected revision is not the current one; re-read and retry.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ConnectionEndpointProbeDto

Property	Type	Required
`detail`	string or null	yes
`httpStatus`	number or null	yes
`outcome`	one of `"REACHABLE"`, `"REFUSED"`, `"UNREACHABLE"`	yes

ConnectionEndpointProbeOutcome

How the reachability probe of the current endpoint ended. null until one has run for the current revision.

Type: one of "REACHABLE", "REFUSED", "UNREACHABLE"

ConnectionEndpointReadiness

NOT_APPLICABLE: the connector takes a static base. MISSING: it takes a per-connection endpoint and none is set, so it cannot run. SET: the endpoint is set.

Type: one of "NOT_APPLICABLE", "MISSING", "SET"

ConnectionResolutionErrorCode

CONNECTION_UNRESOLVED (404): no connection satisfied the resolution ladder. CONNECTION_AMBIGUOUS (409): an owner holds several connections and named no default. CONNECTION_DEFAULT_NOT_ACTIVE (409): the default pointer names a connection that is not ACTIVE; re-point the default or re-activate the connection.

Type: one of "CONNECTION_UNRESOLVED", "CONNECTION_AMBIGUOUS", "CONNECTION_DEFAULT_NOT_ACTIVE"

ConnectionResolutionProblemDto

RFC 9457 problem document of a refused connection resolution. Extension members stay top-level and open.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	ConnectionResolutionErrorCode or string	yes	Stable problem code. A `ConnectionResolutionErrorCode` on a connection-resolution refusal, otherwise the gateway code for the status. `CONNECTION_UNRESOLVED` (404): no connection satisfied the resolution ladder. `CONNECTION_AMBIGUOUS` (409): an owner holds several connections and named no default. `CONNECTION_DEFAULT_NOT_ACTIVE` (409): the default pointer names a connection that is not ACTIVE; re-point the default or re-activate the connection.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ConnectorActionProblemDto

RFC 9457 problem document of a refused connector action. Extension members stay top-level and open, as on ProblemDetailsDto.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`claimedAt`	string (date-time)	no	On `IDEMPOTENCY_KEY_IN_FLIGHT` and `IDEMPOTENCY_OUTCOME_UNKNOWN`: when the original request claimed the key.
`code`	one of `"IDEMPOTENCY_KEY_REUSED"`, `"IDEMPOTENCY_KEY_IN_FLIGHT"`, `"IDEMPOTENCY_OUTCOME_UNKNOWN"` or ConnectionResolutionErrorCode or string	yes	Stable problem code. One of `ConnectorActionIdempotencyCode` on an idempotency-key refusal, one of `ConnectionResolutionErrorCode` on a connection-resolution refusal; otherwise the gateway code for the status. `CONNECTION_UNRESOLVED` (404): no connection satisfied the resolution ladder. `CONNECTION_AMBIGUOUS` (409): an owner holds several connections and named no default. `CONNECTION_DEFAULT_NOT_ACTIVE` (409): the default pointer names a connection that is not ACTIVE; re-point the default or re-activate the connection.
`deadline`	string (date-time)	no	On `IDEMPOTENCY_KEY_IN_FLIGHT`: by this time the request has a recorded outcome or is `IDEMPOTENCY_OUTCOME_UNKNOWN`.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`refusalOrigin`	ConnectorRefusalOrigin	no	Who refused the action. `provider` only when the provider itself refused; absent or `gateway` when the gateway refused without the provider deciding. A `gateway` refusal always states `retry`: `transient` when the same request may succeed later, `after-change` when it never succeeds as sent.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ConnectorAuthKind

Auth kinds the provider supports for user-driven connect. Closed set — the FE uses this to render the connect surface (PAT input, OAuth popup, App-install link, IAM-role config). None means the provider is Xema-hosted and needs no user credential.

Type: one of "pat", "oauth_user", "app_install", "iam_role", "signature_only", "none"

ConnectorCategory

Type: one of "source-code", "packages", "container-images", "trackers", "documentation", "llm", "other"

ConnectorDefinitionOrigin

Authenticated source scope of the exact connector definition.

Type: one of "distribution", "org_installation"

ConnectorKind

Stable provider identifier — matches the Prisma ConnectorKind enum.

Type: string (26 values)

ConnectorOnboardingKind

Type: one of "CREDENTIALS", "APP_INSTALL"

ConnectorRefusalOrigin

Who refused the action. provider only when the provider itself refused; absent or gateway when the gateway refused without the provider deciding. A gateway refusal always states retry: transient when the same request may succeed later, after-change when it never succeeds as sent.

Type: one of "provider", "gateway"

ConnectorStatus

Lifecycle state of the connection row itself.

Type: one of "PENDING_CONFIG", "ACTIVE", "DISABLED", "REVOKED", "ERROR"

ConnectorStatusResponseDto

Property	Type	Required
`discoveredTopology`	DiscoveredTopologyDto	yes
`documentation`	AdapterStatusDto	yes
`scm`	ScmStatusDto	yes
`tracker`	AdapterStatusDto	yes

ConnectorStatusResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	ConnectorStatusResponseDto	yes

CreateOrgConnectionDto

Property	Type	Required	Description
`credentialKind`	string	no	How the credential blob on this connection should be interpreted by the resolver. OPEN registry-backed key, value-identical to the resolve wire: a curated CredentialKind value (e.g. "oauth_user", "api_key") OR a REGISTERED biome-contributed strategy key (UPPER_SNAKE, e.g. "ACME_HMAC"). OPTIONAL and only ever checked for AGREEMENT — the connector descriptor’s declaration is authoritative and a disagreement is a 400.
`isDefault`	boolean	no	Author the `connection.<provider>` default pointer at this connection's own space, as the caller. Omitted: the FIRST connection of a (scope, provider) gets it, a later one does not. `false` on the first connection asks for no default pointer. The outcome is stated in `defaultPointer` of the response; a refusal never fails the create.
`name`	string	no	Human slug identifying this connection among several for the same (org, provider). Lowercase alphanumeric + dashes, max 63 chars. Omitted on the FIRST connection it defaults to 'default'; REQUIRED (409 otherwise) once a connection for the provider already exists.
`projectId`	string	no	Owning project. REQUIRED when scopeTier='project'; FORBIDDEN (400) for any other tier. The connection is owned by (org, project, provider).
`provider`	string	yes	Registered connector key this connection authenticates to — a curated ConnectorKind wire value (e.g. "ATLASSIAN", "GMAIL") or a biome-contributed connector key (e.g. "SAP_S4HANA"). Unregistered keys are rejected with 400 UNKNOWN_PROVIDER_KEY.
`scopeTier`	CredentialOwnerSpaceKind	no	Resolution-ladder tier this connection is owned at. Defaults to 'org'. 'project' REQUIRES projectId; 'user' owns the connection for a single user (defaults to the caller). 'system' is REJECTED here (400) — system-tier rows are operator-created deployment-wide defaults owned by no org, provisioned through the operator custody path, not this API.
`userId`	string	no	Owning user. Only valid when scopeTier='user' (FORBIDDEN otherwise, 400). Defaults to the authenticated caller's own subject when omitted; a value that differs from the caller requires org-admin authority (403 otherwise).

CreateOrgProviderCredentialDto

Property	Type	Required	Description
`fields`	map of string	yes	App-credential field values (schema-validated). NEVER logged or returned.
`providerKey`	string	yes	Provider slug the app credential belongs to.

CreateProjectBindingDto

Property	Type	Required	Description
`adapterKey`	one of `"DOCUMENTATION"`, `"TRACKER"`, `"SCM"`, `"NPM_REGISTRY"`, `"CONTAINER_REGISTRY"`, `"MAIL_INTAKE"`, `"MAIL_EGRESS"`, `"CONVERSATION"`	yes	Adapter key
`bindingConfigJson`	object	no	Binding-specific configuration (e.g., Confluence space mapping)
`orgConnectionId`	string	yes	ID of the org integration to bind to

CreatedOrgConnectionResponseDto

Property	Type	Required	Description
`bindingCount`	number	no	Number of active project bindings that use this integration. Frontend uses this to warn about cascading removal impact.
`createdAt`	string	yes
`createdBy`	string	yes
`credentialsSuspended`	boolean	yes	True when a credential on this connection was written under another endpoint revision: it is suspended and must be re-entered or re-consented before it is used.
`defaultFor`	array of CredentialOwnerSpaceKind	no	Resolution-ladder tier (narrowest wins: user > project > org > system). user/project-tier connections are owned by a single user/project; org-tier connections are tenant-owned; system-tier connections are operator-created deployment-wide defaults consulted last.
`defaultPointer`	DefaultPointerOutcomeDto	yes	Whether the connection became the default for its scope: the `connection.<provider>` pointer authored at its own space as the caller. The connection exists whatever this says.
`defaultRefusal`	DefaultRefusalDto	no	Present when the selection door REFUSED the default for this connection’s provider (a disabled default, or a refused credential): `isDefault` is then false and this says why, instead of reading the refusal as "not the default".
`definitionOrigin`	ConnectorDefinitionOrigin	yes	Authenticated source scope of the exact connector definition.
`definitionOwnerOrgId`	string or null	no	Owning org for an org-installation definition; null for distribution definitions.
`definitionReleaseId`	string	yes	Exact immutable release identity bound when the connection was created.
`endpointProbeOutcome`	ConnectionEndpointProbeOutcome or null	no	How the reachability probe of the current endpoint ended. null until one has run for the current revision.
`endpointProbedAt`	string or null	no	When the current endpoint was last probed.
`endpointReadiness`	ConnectionEndpointReadiness	yes	NOT_APPLICABLE: the connector takes a static base. MISSING: it takes a per-connection endpoint and none is set, so it cannot run. SET: the endpoint is set.
`endpointRevision`	number	yes	Bumped on every endpoint change; send it as expectedRevision when changing the endpoint.
`endpointUrl`	string or null	no	The endpoint (https origin plus base path) this connection talks to. null for a static-base connector and until an admin sets one.
`hasCredentials`	boolean	no	Whether the requesting user has credentials configured
`id`	string	yes
`isDefault`	boolean	no	Whether the `connection.<provider>` default pointer names this connection for the caller (user default, then org default; for a project-tier connection, its project). Read from the pointer through the selection door, never a stored flag. Present on list, get, create and set-default responses.
`name`	string	yes	Human slug identifying this connection among several for the same (org, provider); 'default' for the historical single connection.
`needsReconsent`	boolean	yes	True when the connection is marked needs-reconsent: its credential is distrusted (for example the mailbox or tenant behind it changed) and every use of it is refused until the member consents again. A marked connection can still be `active`.
`orgId`	string or null	no	Owning org. null only for system-tier connections (operator-created deployment-wide defaults).
`projectId`	string or null	no	Owning project. Non-null ONLY for scopeTier='project' connections.
`provider`	string	yes
`reconsentReason`	string or null	no	Why the connection is marked needs-reconsent (a machine code); null when it is not marked.
`scopeTier`	CredentialOwnerSpaceKind	yes	Resolution-ladder tier (narrowest wins: user > project > org > system). user/project-tier connections are owned by a single user/project; org-tier connections are tenant-owned; system-tier connections are operator-created deployment-wide defaults consulted last.
`status`	string	yes
`updatedAt`	string	yes
`userId`	string or null	no	Owning user. Non-null ONLY for scopeTier='user' connections.
`verifiedMailboxAddress`	string or null	no	The mailbox address proved from the provider for the account this connection is consented as, lowercased. null when no address was proved (a non-mail connector, or a mail connection consented before the proof existed — re-consent it).

CreatedOrgConnectionResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	CreatedOrgConnectionResponseDto	yes

CredentialElicitationOpenedDto

Property	Type	Required	Description
`connectorKey`	string or null	no
`expiresAt`	string	yes	ISO-8601 instant after which the form is dead.
`formPath`	string	yes	RELATIVE frontend path that renders the credential form. Carries no host, no token and no secret — it is a link the agent may show.
`providerKey`	string	yes
`ref`	string	yes	Opaque reference to the elicitation. Safe to hand to an agent and to embed in a link: it authorizes nothing on its own (only the named subject, authenticated with their own JWT, may submit against it).
`status`	CredentialElicitationStatus	yes

CredentialElicitationOpenedDtoDataEnvelope

Property	Type	Required	Description
`data`	CredentialElicitationOpenedDto	yes

CredentialElicitationStatus

Type: one of "pending", "submitted", "cancelled", "expired"

CredentialElicitationStatusDto

Property	Type	Required
`connectionId`	string or null	no
`connectorKey`	string or null	no
`expiresAt`	string	yes
`providerKey`	string	yes
`purpose`	string	yes
`ref`	string	yes
`status`	CredentialElicitationStatus	yes
`submittedAt`	string or null	no

CredentialElicitationStatusDtoDataEnvelope

Property	Type	Required	Description
`data`	CredentialElicitationStatusDto	yes

CredentialElicitationSubmittedDto

Property	Type	Required	Description
`connectionId`	string	yes	The connection that now holds the credential.
`ref`	string	yes
`submitted`	boolean	yes	Always true; a failure is an HTTP error.

CredentialElicitationSubmittedDtoDataEnvelope

Property	Type	Required	Description
`data`	CredentialElicitationSubmittedDto	yes

CredentialFieldAcceptsDto

Property	Type	Required	Description
`formats`	array of CredentialFieldFormat	no	Platform-owned value formats; a value satisfying any one is accepted.
`values`	array of string	no	Exact (case-sensitive) values that are accepted.

CredentialFieldFormat

Platform-owned value formats; a value satisfying any one is accepted.

Type: one of "uuid", "dns-name"

CredentialFieldSpecDto

Property	Type	Required	Description
`accepts`	CredentialFieldAcceptsDto	no	The closed set of values the field admits: exactly one of `values`, or any value satisfying one of `formats`. A value outside it is refused when saved and wherever it is used.
`defaultValue`	string	no	The value an optional, non-secret field takes when left blank. Never present on a required or secret field.
`hint`	string	no	Optional secondary hint under the input.
`isSecret`	boolean	yes	DECLARED secrecy. True ⇒ the submitted value goes to credential custody and is never readable back; false ⇒ it is non-secret configuration. Independent of `type`, which only says how to RENDER the input.
`key`	string	yes	Dot-path key the value is submitted under.
`label`	string	yes	Human-readable label for the input.
`placeholder`	string	no	Optional placeholder copy.
`required`	boolean	yes	When true the field must be filled before submit.
`transform`	CredentialFieldTransform	yes	Normalization transform applied before submission.
`type`	CredentialFieldType	yes

CredentialFieldTransform

Normalization transform applied before submission.

Type: one of "NONE", "UPPERCASE", "LOWERCASE", "TRIM"

CredentialFieldType

Type: one of "TEXT", "PASSWORD", "EMAIL", "URL", "JSON_BLOB"

CredentialOwnerSpaceKind

Resolution-ladder tier (narrowest wins: user > project > org > system). user/project-tier connections are owned by a single user/project; org-tier connections are tenant-owned; system-tier connections are operator-created deployment-wide defaults consulted last.

Type: one of "user", "project", "org", "system"

DefaultPointerNotSetReason

Why no pointer was authored. Present when state is not_set.

Type: one of "not_requested", "not_first_connection", "provider_unrepresentable", "forbidden", "refused", "unavailable"

DefaultPointerOutcomeDto

Property	Type	Required	Description
`code`	string	no	The space-registry's code, passed through when it refused the pointer. Open: branch on `reason`, which is closed.
`reason`	DefaultPointerNotSetReason	no	Why no pointer was authored. Present when `state` is `not_set`.
`state`	DefaultPointerState	yes	`set`: the default pointer names this connection. `not_set`: it was not authored; see `reason`.

DefaultPointerState

set: the default pointer names this connection. not_set: it was not authored; see reason.

Type: one of "set", "not_set"

DefaultRefusalDto

Property	Type	Required	Description
`code`	string	no	The custodian's typed refusal code. Present for `materialization_refused`.
`ownerSpaceKind`	CredentialOwnerSpaceKind	no	Resolution-ladder tier (narrowest wins: user > project > org > system). user/project-tier connections are owned by a single user/project; org-tier connections are tenant-owned; system-tier connections are operator-created deployment-wide defaults consulted last.
`reason`	DefaultRefusalReason	yes	`pointer_disabled`: an owner tier disabled the default and the walk stopped there. `materialization_refused`: the custodian refused to release the selected credential.

DefaultRefusalReason

pointer_disabled: an owner tier disabled the default and the walk stopped there. materialization_refused: the custodian refused to release the selected credential.

Type: one of "pointer_disabled", "materialization_refused"

DiscoveredTopologyDto

Property	Type	Required	Description
`available`	boolean	yes

GroupedCatalogDto

Property	Type	Required	Description
`providers`	array of GroupedProviderDto	yes

GroupedCatalogDtoDataEnvelope

Property	Type	Required	Description
`data`	GroupedCatalogDto	yes

GroupedConnectorDto

Property	Type	Required	Description
`adapterKind`	string	yes	Adapter category the connector plugs into (mail, scm, …).
`connectionCredentialKind`	string	yes	How an individual connection to this connector authenticates. OPEN key: a curated CredentialKind value (e.g. "oauth_user") OR a biome-contributed strategy key (UPPER_SNAKE).
`connectorKey`	string	yes	Stable connector key (aligns with ConnectorKind).
`description`	string	yes
`displayName`	string	yes
`iconName`	string	yes	Lucide-react icon name.
`scopes`	array of string	yes	Incremental OAuth scopes this connector requests (empty for None providers).

GroupedProviderDto

Property	Type	Required	Description
`allowOrgOverride`	boolean	yes	Whether an org may override the platform-default app credential (BYO).
`appAuthKind`	ProviderAppAuthKind	yes	How the shared app credential authenticates.
`appCredentialSchema`	array of CredentialFieldSpecDto	yes	Schema of the app-credential fields an admin supplies once (empty for None providers). NEVER any value.
`appCredentialStatus`	ProviderAppCredentialStatus	yes	Per-org app-credential status resolved via the credential broker.
`category`	string	yes	Catalog grouping label (Email, Source control, …).
`connections`	array of ProviderConnectionDto	yes	The connections to this provider that already exist and that the CALLER may be told about — the org's own, plus the caller's own private ones. EMPTY means nothing is connected; it never means "we did not look", because a read failure here fails the request rather than degrading.
`connectors`	array of GroupedConnectorDto	yes
`description`	string	yes
`displayName`	string	yes
`iconName`	string	yes	Lucide-react icon name.
`providerKey`	string	yes	Stable lowercase provider slug (google, smtp, …).
`requiresAppCredential`	boolean	yes	True when an app credential must be provisioned before any connector can be connected (appAuthKind ≠ None).

InboundEndpointDeliveryDecision

accepted — verified, attributed to a tenant and enqueued for durable forward. duplicate — the same (endpoint, idempotency key) was already accepted; the dedupe held and nothing was enqueued a second time.

Type: one of "accepted", "duplicate"

InboundEndpointDeliveryResponseDto

Property	Type	Required	Description
`decision`	InboundEndpointDeliveryDecision	yes	`accepted` — verified, attributed to a tenant and enqueued for durable forward. `duplicate` — the same (endpoint, idempotency key) was already accepted; the dedupe held and nothing was enqueued a second time.
`idempotencyKey`	string	yes	The deterministic idempotency key the edge extracted, echoed so a caller can confirm the edge read the field it meant.

InboundEndpointDeliveryResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	InboundEndpointDeliveryResponseDto	yes

InboundEndpointInstanceDto

Property	Type	Required	Description
`endpointSlug`	string	yes	The inbound endpoint slug (`/webhooks/inbound/<slug>/<endpointToken>`).
`externalKey`	string	yes	The external account id deliveries are matched on: the connection's provider-established installation id, never caller-supplied.
`id`	string	yes	Binding id.
`orgConnectionId`	string	yes	The bound connection.

InboundEndpointInstanceDtoDataEnvelope

Property	Type	Required	Description
`data`	InboundEndpointInstanceDto	yes

InboundEndpointReadiness

unbound - no instance binds the connection to the endpoint. secret-missing - bound, but the connection has no webhook secret (PUT /org-connections/:id/webhook-secret). secret-unresolvable - the connection names a secret the credential broker does not resolve for this organisation; re-provision it. ready - the secret resolves, so deliveries verify.

Type: one of "unbound", "secret-missing", "secret-unresolvable", "ready"

InboundEndpointReadinessDto

Property	Type	Required	Description
`endpointSlug`	string	yes	The inbound endpoint slug.
`orgConnectionId`	string	yes	The connection asked about.
`state`	InboundEndpointReadiness	yes	`unbound` - no instance binds the connection to the endpoint. `secret-missing` - bound, but the connection has no webhook secret (PUT /org-connections/:id/webhook-secret). `secret-unresolvable` - the connection names a secret the credential broker does not resolve for this organisation; re-provision it. `ready` - the secret resolves, so deliveries verify.

InboundEndpointReadinessDtoDataEnvelope

Property	Type	Required	Description
`data`	InboundEndpointReadinessDto	yes

InvokeActionRequestDto

Property	Type	Required	Description
`connectionId`	string	no	Explicit connection row id to execute against.
`idempotencyKey`	string	no	One stable key per logical action, reused on every retry. The same key with the same request returns the recorded outcome instead of acting again; the same key with a different request is refused (422 IDEMPOTENCY_KEY_REUSED) and a duplicate while the first is still running is refused (409 IDEMPOTENCY_KEY_IN_FLIGHT). A request whose provider call gave no definitive answer (it outlived the gateway hard deadline, its holder crashed, or it ended in a timeout, reset, abort, 5xx or unreadable response after the request may have left) answers 409 IDEMPOTENCY_OUTCOME_UNKNOWN with `claimedAt`, and the action is never re-dispatched for that key. If the original call later gets a definitive provider answer, replays return that outcome from then on. The provider may or may not have acted. A failure is recorded only for a definitive refusal (the provider refused with a 4xx, or the gateway refused before dispatch); it replays permanently for that key, including an auth failure after the user reconnects: a new attempt needs a new key. Omit it and the action has no replay protection.
`params`	object	yes	Action input. Closed contract: every key must be declared in the action input schema; an undeclared key (including any credential field) is refused with 400 before the credential is resolved. Credentials are resolved from the connection, never sent in params.
`resourceRef`	object	no	Resource scope (`type:id`) for credential kinds that mint against a specific resource. AppInstall refuses it: an app-installation token is minted only for the resolved connection's own installation, so omit this field for it.

InvokeActionResponseDto

Property	Type	Required	Description
`externalId`	string	no	Provider-native id of the entity created/updated by the action.
`outputs`	object	no	Free-form structured outputs the workflow can read via `steps.<id>.outputs.<field>`. Shape is governed by the adapter's declared action schema.

InvokeActionResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	InvokeActionResponseDto	yes

ListResourcesNotFoundCode

CONNECTION_UNRESOLVED: no connection satisfies the resolution ladder for this provider; connect it first. RESOURCE_TYPE_UNKNOWN: the provider does not expose the requested resource type.

Type: one of "CONNECTION_UNRESOLVED", "RESOURCE_TYPE_UNKNOWN"

ListResourcesNotFoundProblemDto

RFC 9457 problem document of a 404 from resource listing. code is closed.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	ListResourcesNotFoundCode	yes	`CONNECTION_UNRESOLVED`: no connection satisfies the resolution ladder for this provider; connect it first. `RESOURCE_TYPE_UNKNOWN`: the provider does not expose the requested resource type.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ListResourcesResponseDto

Property	Type	Required	Description
`items`	array of ResourceListItemDto	yes
`nextCursor`	string or null	no	Opaque continuation token. Pass back as the `?cursor=` query param on the next request. `null` when no more pages.

ListResourcesResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	ListResourcesResponseDto	yes

OAuthAuthorizeResponseDto

Property	Type	Required	Description
`authorizeUrl`	string	yes	Single-use launch link (on the connector gateway's callback host, valid for two minutes) for the browser to navigate to top-level with `window.location`. It binds the consent to THIS browser with a `__Host-` cookie and redirects to the provider; only this browser can return through the callback. Never open it in another browser or share it.

OAuthAuthorizeResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	OAuthAuthorizeResponseDto	yes

OAuthConnectScopeTier

Type: one of "org", "user"

OAuthConsentCompleteBodyDto

Property	Type	Required	Description
`parkRef`	string	yes	The opaque reference the OAuth callback put on the frontend redirect as `connection_oauth_ref`. Single use; only the member who started the consent (and, at user tier, the owning user) can complete it, and only before the flow expires.

OAuthConsentCompleteResponseDto

Property	Type	Required	Description
`connectionId`	string	yes	The connection the parked consent is now bound to.
`connector`	string	yes	The connector key the consent was for.
`warning`	OAuthConsentCompleteWarning	no	Present when the connection is bound but the provider mail watch could not be established; the mailbox receives no pushes until it is re-armed.

OAuthConsentCompleteResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	OAuthConsentCompleteResponseDto	yes

OAuthConsentCompleteWarning

Present when the connection is bound but the provider mail watch could not be established; the mailbox receives no pushes until it is re-armed.

Type: one of "watch_not_established"

OpenCredentialElicitationDto

Property	Type	Required	Description
`connectorKey`	string	no	Registered CONNECTOR key the resulting connection is for (e.g. "GMAIL"). Must belong to `providerKey`. Omit it only when the provider has exactly one registered connector — an ambiguous provider is rejected at submit time.
`providerKey`	string	yes	Registered PROVIDER key whose credential schema the form renders (e.g. "atlassian", "google"). Unknown keys are rejected with 404.
`purpose`	string	yes	Human-readable reason shown to the user on the form ("Canopy needs Jira access to file the tickets it just planned").
`subjectUserId`	string	no	The user expected to fill the form. Defaults to the caller's own subject; targeting ANOTHER user requires org-admin authority (403 otherwise).

OrgConnectionResponseDto

Property	Type	Required	Description
`bindingCount`	number	no	Number of active project bindings that use this integration. Frontend uses this to warn about cascading removal impact.
`createdAt`	string	yes
`createdBy`	string	yes
`credentialsSuspended`	boolean	yes	True when a credential on this connection was written under another endpoint revision: it is suspended and must be re-entered or re-consented before it is used.
`defaultFor`	array of CredentialOwnerSpaceKind	no	Resolution-ladder tier (narrowest wins: user > project > org > system). user/project-tier connections are owned by a single user/project; org-tier connections are tenant-owned; system-tier connections are operator-created deployment-wide defaults consulted last.
`defaultRefusal`	DefaultRefusalDto	no	Present when the selection door REFUSED the default for this connection’s provider (a disabled default, or a refused credential): `isDefault` is then false and this says why, instead of reading the refusal as "not the default".
`definitionOrigin`	ConnectorDefinitionOrigin	yes	Authenticated source scope of the exact connector definition.
`definitionOwnerOrgId`	string or null	no	Owning org for an org-installation definition; null for distribution definitions.
`definitionReleaseId`	string	yes	Exact immutable release identity bound when the connection was created.
`endpointProbeOutcome`	ConnectionEndpointProbeOutcome or null	no	How the reachability probe of the current endpoint ended. null until one has run for the current revision.
`endpointProbedAt`	string or null	no	When the current endpoint was last probed.
`endpointReadiness`	ConnectionEndpointReadiness	yes	NOT_APPLICABLE: the connector takes a static base. MISSING: it takes a per-connection endpoint and none is set, so it cannot run. SET: the endpoint is set.
`endpointRevision`	number	yes	Bumped on every endpoint change; send it as expectedRevision when changing the endpoint.
`endpointUrl`	string or null	no	The endpoint (https origin plus base path) this connection talks to. null for a static-base connector and until an admin sets one.
`hasCredentials`	boolean	no	Whether the requesting user has credentials configured
`id`	string	yes
`isDefault`	boolean	no	Whether the `connection.<provider>` default pointer names this connection for the caller (user default, then org default; for a project-tier connection, its project). Read from the pointer through the selection door, never a stored flag. Present on list, get, create and set-default responses.
`name`	string	yes	Human slug identifying this connection among several for the same (org, provider); 'default' for the historical single connection.
`needsReconsent`	boolean	yes	True when the connection is marked needs-reconsent: its credential is distrusted (for example the mailbox or tenant behind it changed) and every use of it is refused until the member consents again. A marked connection can still be `active`.
`orgId`	string or null	no	Owning org. null only for system-tier connections (operator-created deployment-wide defaults).
`projectId`	string or null	no	Owning project. Non-null ONLY for scopeTier='project' connections.
`provider`	string	yes
`reconsentReason`	string or null	no	Why the connection is marked needs-reconsent (a machine code); null when it is not marked.
`scopeTier`	CredentialOwnerSpaceKind	yes	Resolution-ladder tier (narrowest wins: user > project > org > system). user/project-tier connections are owned by a single user/project; org-tier connections are tenant-owned; system-tier connections are operator-created deployment-wide defaults consulted last.
`status`	string	yes
`updatedAt`	string	yes
`userId`	string or null	no	Owning user. Non-null ONLY for scopeTier='user' connections.
`verifiedMailboxAddress`	string or null	no	The mailbox address proved from the provider for the account this connection is consented as, lowercased. null when no address was proved (a non-mail connector, or a mail connection consented before the proof existed — re-consent it).

OrgConnectionResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of OrgConnectionResponseDto	yes

OrgConnectionResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	OrgConnectionResponseDto	yes

OrgProviderCredentialDto

Property	Type	Required	Description
`appAuthKind`	ProviderAppAuthKind	yes
`appCredentialSchema`	array of CredentialFieldSpecDto	yes	The app-credential form schema the FE renders. NEVER any value.
`bindingId`	string or null	no	Broker binding id of the org provision (present when configuredByOrg).
`configuredByOrg`	boolean	yes	True when THIS org has its own app-credential provision (overriding the platform default) for this provider.
`createdAt`	string or null	no	When the org provision was created (present when configuredByOrg).
`displayName`	string	yes
`providerKey`	string	yes	Stable lowercase provider slug.
`updatedAt`	string or null	no	When the org provision was last updated (present when configuredByOrg).

OrgProviderCredentialDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of OrgProviderCredentialDto	yes

OrgProviderCredentialDtoDataEnvelope

Property	Type	Required	Description
`data`	OrgProviderCredentialDto	yes

ProblemActionableBy

Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.

Type: one of "user", "org-admin", "platform", "none"

ProblemDetailsDto

RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	string	yes	SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ProblemFieldIssueDto

Property	Type	Required	Description
`code`	string	no	SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem.
`detail`	string	yes	Prose for logs and developers. A frontend localises from `code` + `params` instead.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for this issue's `code`.
`pointer`	string	yes	RFC 6901 JSON Pointer into the request body. Root is "/".

ProblemRetry

What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.

Type: one of "transient", "after-change", "never"

ProjectBindingAdapterKey

Closed set of project-binding adapter kinds this provider supports at the project level. Empty array = the provider has no project-level bindings today (e.g. messaging-only providers).

Type: one of "DOCUMENTATION", "TRACKER", "SCM"

ProjectBindingResponseDto

Property	Type	Required
`adapterKey`	string	yes
`bindingConfigJson`	object	no
`createdAt`	string	yes
`enabled`	boolean	yes
`id`	string	yes
`orgConnectionId`	string	yes
`projectId`	string	yes
`updatedAt`	string	yes

ProjectBindingResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of ProjectBindingResponseDto	yes

ProjectBindingResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	ProjectBindingResponseDto	yes

ProviderAppAuthKind

How the shared app credential authenticates.

Type: one of "oauth2", "app_install", "none"

ProviderAppCredentialStatus

Per-org app-credential status resolved via the credential broker.

Type: one of "not_required", "configured_platform", "configured_org", "unset", "unknown"

ProviderConnectionDto

Property	Type	Required	Description
`connectorKey`	string	yes	The registered CONNECTOR key this connection authenticates to — one provider group's connectors may each hold their own connections.
`createdAt`	string	yes
`defaultFor`	array of CredentialOwnerSpaceKind	no	Resolution-ladder tier (narrowest wins: user > project > org > system). user/project-tier connections are owned by a single user/project; org-tier connections are tenant-owned; system-tier connections are operator-created deployment-wide defaults consulted last.
`defaultRefusal`	DefaultRefusalDto	no	Present when the selection door REFUSED the default for this connection’s provider: `isDefault` is then false and this says why, instead of reading the refusal as "not the default". Absent means no refusal.
`hasCredentials`	boolean	yes	Whether the CALLING person holds a credential on this connection. FALSE on a connection that exists and that this person has never authenticated — the state in which an invocation of theirs would fail to resolve a credential. Computed for the acting user, never for the org.
`id`	string	yes	Connection id — the handle for `PATCH /org-connections/:id/default`.
`isDefault`	boolean	yes	Whether this connection is the default for its (scope, provider) — i.e. the one an invocation that names no `connectionName` resolves. Exactly one connection per tier carries it.
`name`	string	yes	Human slug distinguishing this connection from the org's others for the same provider ('default' for the first one). This is the value a capability invocation names as `connectionName`.
`scopeTier`	CredentialOwnerSpaceKind	yes	Tier this connection is owned at. Only 'org' and 'user' appear here: a 'project' connection resolves only inside its project, and a 'platform' one is an operator-created deployment-wide default owned by no org.
`status`	ConnectorStatus	yes	Lifecycle state of the connection row itself.

ProviderOnboardingManifestDto

Property	Type	Required	Description
`description`	string	yes	One-sentence description shown beneath the provider name.
`displayName`	string	yes	Human-readable provider name shown in the wizard header.
`fields`	array of CredentialFieldSpecDto	no	Field-by-field credential form spec. Required when `kind = CREDENTIALS`.
`hint`	string	no	Hint shown above the credential form (e.g. scope guidance).
`iconName`	string	yes	Lucide-react icon name (e.g. `Globe`, `BookOpen`). The frontend maps the name to a concrete icon component.
`jsonPlaceholder`	string	no	Pretty-printed JSON placeholder used when no `fields` are declared — the wizard falls back to a JSON textarea using this template.
`kind`	ConnectorOnboardingKind	yes
`launchHint`	string	no	Hint shown next to / under the launch button.
`launchLabel`	string	no	Copy for the launch button (e.g. `Install GitHub App`).
`provider`	string	yes	Provider slug (same as `ConnectorAdapterModule.provider`).
`supportedProjectBindingAdapterKinds`	array of ProjectBindingAdapterKey	yes	Closed set of project-binding adapter kinds this provider supports at the project level. Empty array = the provider has no project-level bindings today (e.g. messaging-only providers).

ProviderSummaryDto

Property	Type	Required	Description
`actionSlugs`	array of string	yes	Outbound action slugs the provider implements (e.g. `post-pr-comment`).
`adapterKind`	string	yes	AdapterKind slug the provider plugs into. Built-in kinds: `scm`, `tracker`, `documentation`. Biome-contributed kinds (Phase 7) use their registered slug.
`credentialKind`	string	yes	How an individual connection authenticates. OPEN key: a curated CredentialKind value OR a biome-contributed strategy key (UPPER_SNAKE).
`displayName`	string	yes	Human-readable provider name.
`oauthAuthorizePath`	string	no	Present only for OAuth2 connectors (e.g. Gmail). Relative path on connector-gateway-api that starts the OAuth consent driver. The frontend opens `${connectorGatewayBaseUrl}${oauthAuthorizePath}` with `&orgId=&frontendBaseUrl=&returnPath=` appended; the endpoint 302-redirects the browser to the provider consent screen. Absent for CREDENTIALS connectors (SMTP/IMAP), which connect via the `onboarding.fields` form.
`onboarding`	ProviderOnboardingManifestDto	yes	Install-wizard onboarding manifest: display copy, icon, and either credential field schema or app-install launch copy.
`provider`	string	yes	Unique provider slug (e.g. `github`, `linear`, `stripe`).
`resourceTypes`	array of string	yes	Resource type slugs the provider can list (e.g. `repo`, `branch`, `project`).

ProviderSummaryDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of ProviderSummaryDto	yes

ProvidersCatalogCategoryDto

Property	Type	Required	Description
`id`	ConnectorCategory	yes
`label`	string	yes	Human-readable category label.
`providers`	array of ProvidersCatalogProviderDto	yes

ProvidersCatalogDto

Property	Type	Required	Description
`categories`	array of ProvidersCatalogCategoryDto	yes

ProvidersCatalogDtoDataEnvelope

Property	Type	Required	Description
`data`	ProvidersCatalogDto	yes

ProvidersCatalogProviderDto

Property	Type	Required	Description
`alwaysAvailable`	boolean	yes	True when the provider needs no org connection and no user credential (Xema-hosted system-shareable providers); FE renders an "Always available" badge and skips the Connect flow.
`authKinds`	array of ConnectorAuthKind	yes	Auth kinds the provider supports for user-driven connect. Closed set — the FE uses this to render the connect surface (PAT input, OAuth popup, App-install link, IAM-role config). `None` means the provider is Xema-hosted and needs no user credential.
`category`	ConnectorCategory	yes	Category this provider rolls up to (mirrored from the outer category so FE list components can re-group without re-walking the manifest).
`id`	ConnectorKind	yes	Stable provider identifier — matches the Prisma `ConnectorKind` enum.
`label`	string	yes	Human-readable provider name.
`tier`	RegistryVisibilityTier	yes	Visibility tier of the provider — drives "Always available" badging in the hub and ACL behaviour at the registry layer for Xema-hosted providers.
`tierBadge`	string	no	Optional short label rendered alongside the tier badge — e.g. "Xema-hosted" for system-shareable providers. Omitted when the tier alone is self-explanatory.

RegistryVisibilityTier

Visibility tier of the provider — drives "Always available" badging in the hub and ACL behaviour at the registry layer for Xema-hosted providers.

Type: one of "system", "system-shareable", "org", "external"

RemoveConnectionCredentialOverride

Type: one of "break-dependent-project-bindings"

RemoveCredentialsResultDto

Property	Type	Required	Description
`connectionId`	string	yes	The connection the credential was removed from.
`credentialsRemoved`	number	yes	How many credential rows were removed.
`note`	string	yes	What just happened and what is still true, in the caller’s own words — including, when bindings were broken, what has to be done about them.
`projectBindingsBroken`	number	yes	How many project bindings resolved through the removed credential and will now fail at the custody seam. Non-zero ONLY on an overridden removal — otherwise the removal was refused instead.
`userId`	string	yes	The member whose credential was removed, as resolved and fenced by the server — echoed back so the answer names its own subject.

RemoveCredentialsResultDtoDataEnvelope

Property	Type	Required	Description
`data`	RemoveCredentialsResultDto	yes

ResourceListItemDto

Property	Type	Required	Description
`description`	string	no	Optional secondary description (repo description, channel topic).
`id`	string	yes	Provider-opaque identifier — what the install wizard stores in the selector.
`label`	string	yes	Human-readable label rendered by the install wizard.
`metadata`	map of string	no	Provider-opaque key/value pairs the install wizard MAY display (branch count, member count, last-activity timestamp). Never used for routing or authorization.

RotateOrgProviderCredentialDto

Property	Type	Required	Description
`fields`	map of string	yes	New app-credential field values (schema-validated). NEVER logged or returned.

ScmRepositoryStatusDto

Property	Type	Required
`effectiveCapabilities`	map of boolean	no
`health`	one of `"NOT_CONFIGURED"`, `"CONFIGURED_UNTESTED"`, `"HEALTHY"`, `"DEGRADED"`, `"MISCONFIGURED"`, `"UNAVAILABLE"`	yes
`id`	string	yes
`isPrimary`	boolean	yes
`provider`	string	yes
`role`	string	yes
`slug`	string	yes
`supportedCapabilities`	map of boolean	no
`targetBranch`	string	yes

ScmStatusDto

Property	Type	Required
`configured`	boolean	yes
`effectiveCapabilities`	map of boolean	no
`health`	one of `"NOT_CONFIGURED"`, `"CONFIGURED_UNTESTED"`, `"HEALTHY"`, `"DEGRADED"`, `"MISCONFIGURED"`, `"UNAVAILABLE"`	yes
`lastError`	object or null	no
`mergeStrategy`	string	no
`operations`	object	no
`primaryRepositoryId`	string	no
`provider`	string	no
`refreshMode`	string	no
`repositories`	array of ScmRepositoryStatusDto	no
`sourceOfTruth`	string	no
`supportedCapabilities`	map of boolean	no

SetWebhookSecretDto

Property	Type	Required	Description
`secret`	string	yes	The provider's webhook signing secret. Written straight to the credential broker and never persisted by this service; it is not readable back through any route.

SubmitCredentialElicitationDto

Property	Type	Required	Description
`fields`	map of string	yes	The filled credential form, keyed by the provider credential schema field keys. Posted by the BROWSER with the user's own JWT — this body never passes through an agent, a transcript or the event ledger.

TestConnectionResponseDto

Property	Type	Required
`effectiveCapabilities`	map of boolean	no
`errorDetail`	string	no
`health`	one of `"NOT_CONFIGURED"`, `"CONFIGURED_UNTESTED"`, `"HEALTHY"`, `"DEGRADED"`, `"MISCONFIGURED"`, `"UNAVAILABLE"`	yes
`result`	one of `"SUCCESS"`, `"AUTH_INVALID"`, `"PERMISSION_INSUFFICIENT"`, `"CONFIG_INCOMPLETE"`, `"PROVIDER_UNREACHABLE"`, `"RATE_LIMITED"`	yes

TestConnectionResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	TestConnectionResponseDto	yes

UpdateProjectBindingDto

Property	Type	Required	Description
`bindingConfigJson`	object	no	Updated binding configuration
`enabled`	boolean	no	Enable or disable the binding

WebhookEndpointDto

Property	Type	Required	Description
`bindingId`	string	yes	Id of the credential-broker binding that holds the sealed secret. A reference, not secret material; unchanged by rotation. A workload that signs deliveries resolves the same binding.
`endpointPath`	string or null	yes	Path to register as the webhook URL at the provider, appended to the deployment's public ingress origin. Returned ONCE, when the endpoint token is issued; null when a token was already issued (only its digest is stored, so it cannot be shown again; rotate it to obtain a new one).

WebhookEndpointDtoDataEnvelope

Property	Type	Required	Description
`data`	WebhookEndpointDto	yes

WebhookEndpointTokenRotationDto

Property	Type	Required	Description
`endpointPath`	string	yes	The registry-door path for this connection with the new token, appended to the deployment's public ingress origin.
`endpointToken`	string	yes	The new endpoint token, returned exactly once. Append it to `/webhooks/inbound/:slug/` for each inbound endpoint of the connection. The previous token is refused from the moment this response is sent.

WebhookEndpointTokenRotationDtoDataEnvelope

Property	Type	Required	Description
`data`	WebhookEndpointTokenRotationDto	yes