Update OAuth credentials

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. Since a null inside a map is the delete mechanism, none of the three accepts null for the whole field — customJwtClaims: null, customBodyParams: null or customHeaders: null is rejected with a 400 rather than ignored. Clear a map by listing each of its keys with a null value. Because null is spent on deletion, a claim cannot be set to JSON null either, on this endpoint or on create. mtlsClientSignedCert is a scalar rather than a map, so null there does remove it.

Endpoint Permissions: Owner, Admin, Non-Signing Admin.

PATCH

webhooks_settings

oauth

{webhookOauthId}

TypeScript

const response: Promise<FireblocksResponse<WebhookOAuthCredentials>> = fireblocks.webhooksV2.updateWebhookOAuth(webhooksV2ApiUpdateWebhookOAuthRequest);

curl --request PATCH \
  --url https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId} \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production treasury gateway",
  "clientId": "my-client-id",
  "clientSecret": "my-new-client-secret",
  "url": "https://auth.example.com/oauth/token",
  "authMethod": "client_secret_jwt",
  "customJwtClaims": {
    "aud": "https://auth.example.com",
    "resource": null
  },
  "customBodyParams": {
    "scope": "payments.read payments.write",
    "audience": null
  },
  "customHeaders": {
    "x-api-key": "gateway-key",
    "x-tenant": null
  },
  "mtlsClientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}
'

const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Production treasury gateway',
    clientId: 'my-client-id',
    clientSecret: 'my-new-client-secret',
    url: 'https://auth.example.com/oauth/token',
    authMethod: 'client_secret_jwt',
    customJwtClaims: {aud: 'https://auth.example.com', resource: null},
    customBodyParams: {scope: 'payments.read payments.write', audience: null},
    customHeaders: {'x-api-key': 'gateway-key', 'x-tenant': null},
    mtlsClientSignedCert: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----'
  })
};

fetch('https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Production treasury gateway',
    'clientId' => 'my-client-id',
    'clientSecret' => 'my-new-client-secret',
    'url' => 'https://auth.example.com/oauth/token',
    'authMethod' => 'client_secret_jwt',
    'customJwtClaims' => [
        'aud' => 'https://auth.example.com',
        'resource' => null
    ],
    'customBodyParams' => [
        'scope' => 'payments.read payments.write',
        'audience' => null
    ],
    'customHeaders' => [
        'x-api-key' => 'gateway-key',
        'x-tenant' => null
    ],
    'mtlsClientSignedCert' => '-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId}"

	payload := strings.NewReader("{\n  \"name\": \"Production treasury gateway\",\n  \"clientId\": \"my-client-id\",\n  \"clientSecret\": \"my-new-client-secret\",\n  \"url\": \"https://auth.example.com/oauth/token\",\n  \"authMethod\": \"client_secret_jwt\",\n  \"customJwtClaims\": {\n    \"aud\": \"https://auth.example.com\",\n    \"resource\": null\n  },\n  \"customBodyParams\": {\n    \"scope\": \"payments.read payments.write\",\n    \"audience\": null\n  },\n  \"customHeaders\": {\n    \"x-api-key\": \"gateway-key\",\n    \"x-tenant\": null\n  },\n  \"mtlsClientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Production treasury gateway\",\n  \"clientId\": \"my-client-id\",\n  \"clientSecret\": \"my-new-client-secret\",\n  \"url\": \"https://auth.example.com/oauth/token\",\n  \"authMethod\": \"client_secret_jwt\",\n  \"customJwtClaims\": {\n    \"aud\": \"https://auth.example.com\",\n    \"resource\": null\n  },\n  \"customBodyParams\": {\n    \"scope\": \"payments.read payments.write\",\n    \"audience\": null\n  },\n  \"customHeaders\": {\n    \"x-api-key\": \"gateway-key\",\n    \"x-tenant\": null\n  },\n  \"mtlsClientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Production treasury gateway",
  "clientId": "my-client-id",
  "url": "https://auth.example.com/oauth/token",
  "authMethod": "client_secret_basic",
  "createdAt": 1625097600000,
  "updatedAt": 1625097600000,
  "customJwtClaims": [
    "aud",
    "resource"
  ],
  "customBodyParams": [
    "scope"
  ],
  "customHeaders": [
    "X-Api-Key"
  ],
  "mtlsClientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

{
  "message": "<string>",
  "code": 123
}

Path Parameters

webhookOauthId

string<uuid>

required

The unique identifier of the OAuth credentials

Example:

"44fcead0-7053-4831-a53a-df7fb90d440f"

Body

application/json

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. Because null inside a map means delete, none of the three is nullable as a whole — customJwtClaims: null and friends are rejected with a 400. Clear a map by naming each key with a null value. mtlsClientSignedCert is a scalar, so null there does remove it.

name

string

A label for this credential set. Omit to leave it unchanged.

Required string length: 1 - 128

Example:

"Production treasury gateway"

clientId

string

OAuth client ID. Omit to leave it unchanged.

Required string length: 1 - 255

Example:

"my-client-id"

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.

Required string length: 1 - 480

Example:

"my-new-client-secret"

url

string

Token endpoint URL. HTTPS on port 443 only, and the host must resolve publicly. Omit to leave it unchanged.

Maximum string length: 2048

Pattern: ^https://

Example:

"https://auth.example.com/oauth/token"

authMethod

string

client_secret_basic, client_secret_post or client_secret_jwt. Omit to leave it unchanged — it does not revert to the default.

Example:

"client_secret_jwt"

customJwtClaims

object | null

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.

Show child attributes

Example:

{
  "aud": "https://auth.example.com",
  "resource": null
}

customBodyParams

object | null

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.

Show child attributes

Example:

{
  "scope": "payments.read payments.write",
  "audience": null
}

customHeaders

object | null

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/Authorization/ Content-Length/Host reserved, resulting set under 16 KB, values write-only.

Show child attributes

Example:

{
  "x-api-key": "gateway-key",
  "x-tenant": null
}

mtlsClientSignedCert

string | null

PEM-encoded client certificate for mTLS. Must be a valid X.509 certificate inside its validity window. Omit to leave it unchanged, or send null to remove it.

Example:

"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

Response

Updated OAuth credentials object

A stored OAuth 2.0 client credential set, referenced by webhooks through their webhookOauthId. When a webhook references one, the dispatcher fetches a bearer token from url before each delivery and attaches it as Authorization: Bearer {token}. 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.

string<uuid>

required

The id of the OAuth credentials. Pass this as a webhook's webhookOauthId to attach them.

Example:

"123e4567-e89b-12d3-a456-426614174000"

name

string

required

The label given to this credential set.

Example:

"Production treasury gateway"

clientId

string

required

OAuth client ID used to authenticate with the token endpoint.

Example:

"my-client-id"

url

string

required

Token endpoint URL.

Example:

"https://auth.example.com/oauth/token"

authMethod

string

default:client_secret_basic

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.

Example:

"client_secret_basic"

createdAt

integer<int64>

required

The date and time the OAuth credentials were created, in milliseconds.

Example:

1625097600000

updatedAt

integer<int64>

required

The date and time the OAuth credentials were last updated, in milliseconds.

Example:

1625097600000

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.

Example:

["aud", "resource"]

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.

Example:

["scope"]

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.

Example:

["X-Api-Key"]

mtlsClientSignedCert

string

PEM-encoded client certificate used for mTLS when fetching OAuth tokens.

Example:

"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

TypeScript

const response: Promise<FireblocksResponse<WebhookOAuthCredentials>> = fireblocks.webhooksV2.updateWebhookOAuth(webhooksV2ApiUpdateWebhookOAuthRequest);

curl --request PATCH \
  --url https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId} \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production treasury gateway",
  "clientId": "my-client-id",
  "clientSecret": "my-new-client-secret",
  "url": "https://auth.example.com/oauth/token",
  "authMethod": "client_secret_jwt",
  "customJwtClaims": {
    "aud": "https://auth.example.com",
    "resource": null
  },
  "customBodyParams": {
    "scope": "payments.read payments.write",
    "audience": null
  },
  "customHeaders": {
    "x-api-key": "gateway-key",
    "x-tenant": null
  },
  "mtlsClientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}
'

const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Production treasury gateway',
    clientId: 'my-client-id',
    clientSecret: 'my-new-client-secret',
    url: 'https://auth.example.com/oauth/token',
    authMethod: 'client_secret_jwt',
    customJwtClaims: {aud: 'https://auth.example.com', resource: null},
    customBodyParams: {scope: 'payments.read payments.write', audience: null},
    customHeaders: {'x-api-key': 'gateway-key', 'x-tenant': null},
    mtlsClientSignedCert: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----'
  })
};

fetch('https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Production treasury gateway',
    'clientId' => 'my-client-id',
    'clientSecret' => 'my-new-client-secret',
    'url' => 'https://auth.example.com/oauth/token',
    'authMethod' => 'client_secret_jwt',
    'customJwtClaims' => [
        'aud' => 'https://auth.example.com',
        'resource' => null
    ],
    'customBodyParams' => [
        'scope' => 'payments.read payments.write',
        'audience' => null
    ],
    'customHeaders' => [
        'x-api-key' => 'gateway-key',
        'x-tenant' => null
    ],
    'mtlsClientSignedCert' => '-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId}"

	payload := strings.NewReader("{\n  \"name\": \"Production treasury gateway\",\n  \"clientId\": \"my-client-id\",\n  \"clientSecret\": \"my-new-client-secret\",\n  \"url\": \"https://auth.example.com/oauth/token\",\n  \"authMethod\": \"client_secret_jwt\",\n  \"customJwtClaims\": {\n    \"aud\": \"https://auth.example.com\",\n    \"resource\": null\n  },\n  \"customBodyParams\": {\n    \"scope\": \"payments.read payments.write\",\n    \"audience\": null\n  },\n  \"customHeaders\": {\n    \"x-api-key\": \"gateway-key\",\n    \"x-tenant\": null\n  },\n  \"mtlsClientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fireblocks.io/v1/webhooks_settings/oauth/{webhookOauthId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Production treasury gateway\",\n  \"clientId\": \"my-client-id\",\n  \"clientSecret\": \"my-new-client-secret\",\n  \"url\": \"https://auth.example.com/oauth/token\",\n  \"authMethod\": \"client_secret_jwt\",\n  \"customJwtClaims\": {\n    \"aud\": \"https://auth.example.com\",\n    \"resource\": null\n  },\n  \"customBodyParams\": {\n    \"scope\": \"payments.read payments.write\",\n    \"audience\": null\n  },\n  \"customHeaders\": {\n    \"x-api-key\": \"gateway-key\",\n    \"x-tenant\": null\n  },\n  \"mtlsClientSignedCert\": \"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Production treasury gateway",
  "clientId": "my-client-id",
  "url": "https://auth.example.com/oauth/token",
  "authMethod": "client_secret_basic",
  "createdAt": 1625097600000,
  "updatedAt": 1625097600000,
  "customJwtClaims": [
    "aud",
    "resource"
  ],
  "customBodyParams": [
    "scope"
  ],
  "customHeaders": [
    "X-Api-Key"
  ],
  "mtlsClientSignedCert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

{
  "message": "<string>",
  "code": 123
}

Introduction

Errors & Statuses

Data Objects

API Endpoints

Update OAuth credentials

Path Parameters

Body

Response