Skip to main content
POST
Bind an org unit to a capability provider
Binds one org unit to an enabled provider record of a bindable capability (file_hosting, source_control or typed_judgments), as the Console’s binding editor does. The credential must be the unit’s own: an approved credential for the record’s connection homed exactly at the unit. A credential at the platform or at an ancestor does not count, so a binding never makes an org depend on a credential owned elsewhere. Read the result back with getCapabilityBindingReadiness.

Authority and retries

Requires platform:manage at the org unit: a grant at the platform, at one of the unit’s ancestors or at the unit itself. Elsewhere the answer is 403 and nothing is written. A Forge agent can never hold platform:manage. The write is recorded in the audit log under the calling key or External App, never a person. Send an Idempotency-Key to make a retry safe. The same key and the same body within 24 hours return the recorded 200 only while you still hold platform:manage at the org unit the recorded result names; otherwise the answer is 409 idempotency_result_unavailable, and the write never runs twice. The same key with a different body is 422.

Errors

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

domain
string
required

A bindable capability domain: file_hosting, source_control or typed_judgments

Minimum string length: 1

Body

application/json

The bindable capability domain (file_hosting, source_control, typed_judgments), the orgUnitId to bind and the enabled providerKey to bind it to.

orgUnitId
string
required

The org unit to bind

Minimum string length: 1
providerKey
string
required

An enabled provider record of the domain

Minimum string length: 1

Response

Bind an org unit to a capability provider

data
object
required

The org unit now bound to providerKey for the capability domain.

meta
object
required