Skip to main content
POST
Set a provider's options
Replaces one provider’s global options, validated against the provider’s options schema. The response is the provider’s enabled state and changed. An option that would repoint the provider at another host (apiUrl, baseUrl, or any *Url key or URL field in the provider’s options schema) can only be set in the Console: over the API it is 400 bad_request, and the message names the option. Options never hold a secret: a secret-shaped key or value is 400 too; store a secret as a Credential on the vendor’s Connection.

Authority and retries

Requires platform:manage at the platform scope. Capability and provider configuration is deployment-wide, so a credential granted platform:manage only at an org unit is refused with 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 platform scope; 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

providerKey
string
required

The provider key, as listProviders returns it (e.g. slack)

Minimum string length: 1

Body

application/json

The provider key and its global options, validated against the provider's options schema. Options never hold a secret, and URL overrides (apiUrl, baseUrl, any *Url) are Console-only.

options
object
required

The provider's global options, replacing the stored ones

Response

Set a provider's options

data
object
required

A provider after the write: whether it is enabled, and whether the write changed its enabled state or options.

meta
object
required