Skip to main content
PATCH
Set the engineering scope definition
Sets the engineering scope from startsAt: engineeringOrgUnitIds (1 to 20 active org units under the Gloo organization, outside every customer subtree, none inside another) and an optional endsAt. Name the effective definition as previousId with the expectedRevision you read from Get engineering scope: a change from its own start corrects it in place, and a later start ends it there and starts a successor. With no definition effective, send both as null. A previousId that is not an engineering scope definition answers 404; a stale one or revision answers 409 ending (ENGINEERING_SCOPE_CHANGED). A start before today needs correctionReason (at most 1,000 characters). Returns 200 with the definition that now takes effect at startsAt. Needs workforce:manage at the platform scope (Console parity): a grant that covers only some org units receives 403. The credential’s scopes must include workforce:read as well as workforce:manage, because the success returns the written row; otherwise 403 naming workforce:read, and nothing changes. The command is the Console’s own, so its validation, revision and audit rules apply unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console’s code in parentheses. The result never names who created or updated the row. Send an Idempotency-Key to make a retry safe: a same-key retry within 24 hours returns the recorded result only while your scopes still include workforce:read and you still hold workforce:manage at the platform scope; otherwise 409 idempotency_result_unavailable, and the change never runs twice.

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

Body

application/json
engineeringOrgUnitIds
string[]
required

The engineering org units, 1 through 20, none inside another.

Required array length: 1 - 20 elements

An active org unit under the Gloo organization, outside every customer subtree.

Minimum string length: 1
startsAt
integer
required

When the definition takes effect, UTC midnight epoch milliseconds.

Required range: 0 <= x <= 9007199254740991
previousId
string | null
required

The definition this one corrects or succeeds, or null when none is effective.

Minimum string length: 1
expectedRevision
integer | null
required

The revision of previousId you last read, or null exactly when it is null.

Required range: x >= 0
endsAt
integer

When the definition ends (after startsAt); omit for open-ended, UTC midnight epoch milliseconds.

Required range: 0 <= x <= 9007199254740991
correctionReason
string

Required (at most 1,000 characters) when startsAt is before today (UTC).

Response

Success

data
object
required
meta
object
required