--- title: "Update OAuth credentials" method: PATCH path: "/webhooks_settings/oauth/{webhookOauthId}" tags: ["Webhooks V2"] --- # Update OAuth credentials `PATCH /webhooks_settings/oauth/{webhookOauthId}` ## Request - Base URL: `https://api.fireblocks.io/v1` - URL: `https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId}` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Updates only the fields present in the request; anything omitted is left as it is. Sending `clientSecret` on its own rotates the secret for every webhook using these credentials. `customJwtClaims`, `customBodyParams` and `customHeaders` are all merged key by key rather than replaced, the same way a webhook's own `customHeaders` behaves: a key sent with a value is added or overwritten, a key sent with a `null` value is deleted, and a key you omit is left alone. Setting one of the three to `null` as a whole clears that map, which is the quick way to empty it without naming every key. There is no ambiguity between the two uses of `null` — one names an entry to delete, the other names the field. A claim cannot be set to JSON `null`, though, on this endpoint or on create, because `null` is spent on deletion. `webhookMtlsId` is a scalar rather than a map, so `null` there does remove it. **Endpoint Permissions:** Owner, Admin, Non-Signing Admin. ## Path parameters - `webhookOauthId` string, uuid, required ## Request body - UpdateWebhookOauthRequest: A partial update. Every field is optional and an omitted field is left as it is, so `{ "clientSecret": "new-secret" }` rotates the secret and changes nothing else. A rotation applies to every webhook referencing these credentials. The three custom maps merge. A key with a value is upserted, a key with `null` is deleted, a key you leave out is untouched, and the whole field set to `null` clears the map. There is no ambiguity between the two uses of `null` — one names an entry, the other names the field. `webhookMtlsId` is a scalar, so `null` there removes it. - `name` string: A label for this credential set. Omit to leave it unchanged. - `clientId` string: OAuth client ID. Omit to leave it unchanged. - `clientSecret` string: A new OAuth client secret. Limited to 480 bytes when UTF-8 encoded, so a secret using non-ASCII characters fits fewer than 480 of them. Write-only — never returned in any response. Send this on its own to rotate the secret without changing anything else. Omit to leave it unchanged. - `url` string: Token endpoint URL. HTTPS on port 443 only, and the host must resolve publicly. Omit to leave it unchanged. - `authMethod` string: `client_secret_basic`, `client_secret_post` or `client_secret_jwt`. Omit to leave it unchanged — it does not revert to the default. - `customJwtClaims` WebhookOauthCustomJwtClaimsUpdate, nullable: A delta applied to the JWT assertion claims. A claim with a value is added or replaced, a claim with `null` is deleted, and a claim you leave out is untouched. So `{ "aud": "https://auth.example.com", "resource": null }` sets `aud`, drops `resource`, and changes nothing else. Send `customJwtClaims: null` to clear every claim in one call. That does not collide with a `null` value on a name: one names the claim to delete, the other names the whole field. Same rules as on create: any JSON type except `null`, `iss`/`sub`/`jti`/`iat`/`exp` reserved, names case-sensitive, resulting set under 16 KB, values write-only. - `customBodyParams` WebhookOauthCustomBodyParamsUpdate, nullable: A delta applied to the token request body parameters. A parameter with a value is added or replaced, a parameter with `null` is deleted, and one you leave out is untouched. So `{ "scope": "payments.read", "audience": null }` sets `scope`, drops `audience`, and changes nothing else. Send `customBodyParams: null` to clear every parameter in one call. That does not collide with a `null` value on a name: one names the parameter to delete, the other names the whole field. Same rules as on create: string values only, `grant_type`/`client_id`/`client_secret`/ `client_assertion`/`client_assertion_type` reserved, names case-sensitive, resulting set under 16 KB, values write-only. - `customHeaders` WebhookOauthCustomHeadersUpdate, nullable: A delta applied to the token request headers — not the webhook delivery headers. A header with a value is added or replaced, a header with `null` is deleted, and one you leave out is untouched. So `{ "X-Api-Key": "new-key", "X-Tenant": null }` rotates `X-Api-Key`, drops `X-Tenant`, and changes nothing else. Send `customHeaders: null` to clear every header in one call. That does not collide with a `null` value on a name: one names the header to delete, the other names the whole field. Names are case-insensitive, so a `null` under one casing deletes a header stored under another, and names are stored and returned lowercased. Same rules as on create: string values only, `Content-Type`, `Content-Length` and `Host` reserved, `Authorization` only with `client_secret_post` or `client_secret_jwt`, resulting set under 16 KB, values write-only. - `webhookMtlsId` string, uuid, nullable: The id of the mTLS configuration presented to the token endpoint, from `/v1/webhooks_settings/mtls`. Omit to leave it unchanged, or send `null` to stop using mTLS for the token request. Requires the mTLS feature to be enabled for the workspace (`403` otherwise), a configuration of this workspace (`404` otherwise), and one linked to a private key (`400` otherwise). ## Response `200` Updated OAuth credentials object - WebhookOauthCredentials: A stored OAuth 2.0 client credential set, referenced by webhooks through their `webhookOauthId`. Deliveries for a webhook that references one carry `Authorization: Bearer {token}`, using a token fetched from `url` and cached until it expires, so your authorization server sees far fewer token requests than deliveries. Secret material is never returned: `clientSecret` is absent from this schema entirely, and the `customJwtClaims`, `customBodyParams` and `customHeaders` fields are reduced to their names, without the configured values. - `id` string, uuid, required: The id of the OAuth credentials. Pass this as a webhook's `webhookOauthId` to attach them. - `name` string, required: The label given to this credential set. - `clientId` string, required: OAuth client ID used to authenticate with the token endpoint. - `url` string, required: Token endpoint URL. - `authMethod` string, required: How the client credentials are presented to the token endpoint: `client_secret_basic`, `client_secret_post` or `client_secret_jwt`. Credentials created without this field report `client_secret_basic`, which is what they use. - `customJwtClaims` string[]: Names of the additional claims placed in the JWT assertion. Claim values are write-only and are never returned. Absent when no custom claims are configured. - `customBodyParams` string[]: Names of the additional parameters added to the token request body. Parameter values are write-only and are never returned. Absent when no custom parameters are configured. - `customHeaders` string[]: Names of the additional HTTP headers added to **the token request sent to the authorization server** — not to the webhook delivery, which has its own separate `customHeaders`. Header values are write-only and are never returned. Absent when no custom headers are configured. - `webhookMtlsId` string, uuid: The id of the mTLS configuration presented to the token endpoint. Absent when the token request does not use mTLS. Read the certificate from `/v1/webhooks_settings/mtls/{id}`. - `createdAt` integer, required: The date and time the OAuth credentials were created, in milliseconds. - `updatedAt` integer, required: The date and time the OAuth credentials were last updated, in milliseconds. ## Other responses - `default`: Error Response --- [API](https://skmtc.dev/fireblocks/apis/fireblocks-api.md) - [All operations](https://skmtc.dev/fireblocks/apis/fireblocks-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fireblocks/apis/fireblocks-api/revisions/4eba9965659a?raw)