Create OAuth credentials

POST

webhooks_settings

oauth

TypeScript

const response: Promise<FireblocksResponse<WebhookOAuthCredentials>> = fireblocks.webhooksV2.createWebhookOAuth(webhooksV2ApiCreateWebhookOAuthRequest);

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

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

fetch('https://api.fireblocks.io/v1/webhooks_settings/oauth', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Production treasury gateway',
    'clientId' => 'my-client-id',
    'clientSecret' => 'my-client-secret',
    'url' => 'https://auth.example.com/oauth/token',
    'authMethod' => 'client_secret_basic',
    'customJwtClaims' => [
        'aud' => 'https://auth.example.com',
        'email_verified' => true
    ],
    'customBodyParams' => [
        'scope' => 'payments.read payments.write'
    ],
    'customHeaders' => [
        'x-api-key' => 'gateway-key'
    ],
    '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"

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

	req, _ := http.NewRequest("POST", 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")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Production treasury gateway\",\n  \"clientId\": \"my-client-id\",\n  \"clientSecret\": \"my-client-secret\",\n  \"url\": \"https://auth.example.com/oauth/token\",\n  \"authMethod\": \"client_secret_basic\",\n  \"customJwtClaims\": {\n    \"aud\": \"https://auth.example.com\",\n    \"email_verified\": true\n  },\n  \"customBodyParams\": {\n    \"scope\": \"payments.read payments.write\"\n  },\n  \"customHeaders\": {\n    \"x-api-key\": \"gateway-key\"\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
}

Headers

Idempotency-Key

string

A unique identifier for the request. If the request is sent multiple times with the same idempotency key, the server will return the same response as the first request. The idempotency key is valid for 24 hours.

Body

application/json

A new reusable OAuth 2.0 client credential set. Attach it to a webhook by passing the returned id as that webhook's webhookOauthId. Several webhooks may share one credential set, so rotating its client secret covers all of them at once.

name

string

required

A label for this credential set, shown when listing them.

Required string length: 1 - 128

Example:

"Production treasury gateway"

clientId

string

required

OAuth client ID used to authenticate with the token endpoint.

Required string length: 1 - 255

Example:

"my-client-id"

clientSecret

string

required

OAuth client secret. Write-only — never returned. Limited to 480 bytes UTF-8 encoded. With client_secret_jwt it signs the assertion rather than being sent.

Required string length: 1 - 480

Example:

"my-client-secret"

url

string

required

Token endpoint URL. HTTPS on port 443 only, and the host must resolve publicly — localhost and private, link-local or loopback addresses are rejected.

Maximum string length: 2048

Pattern: ^https://

Example:

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

authMethod

string

default:client_secret_basic

How the client credentials reach the token endpoint. client_secret_basic uses an HTTP Basic header, client_secret_post uses form fields in the body, and client_secret_jwt sends a JWT assertion signed with the secret, so the secret itself is never transmitted. Defaults to client_secret_basic.

Example:

"client_secret_basic"

customJwtClaims

object | null

Extra claims for the JWT assertion. Used only when authMethod is client_secret_jwt. The usual one to set is aud, which defaults to the token endpoint URL; some authorization servers expect their own identifier instead. A value may be any JSON type except null — null is reserved for deleting a claim on update. iss, sub, jti, iat and exp are set by Fireblocks and cannot be overridden. Names are case-sensitive. The whole object must be under 16 KB. Values are write-only; responses return only the claim names. On update this merges claim by claim rather than replacing — see WebhookOAuthCustomJwtClaimsUpdate.

Show child attributes

Example:

{
  "aud": "https://auth.example.com",
  "email_verified": true
}

customBodyParams

object | null

Extra parameters for the token request body — scope most commonly, sometimes audience or resource. Applies to every authentication method. Values must be strings, because the token request body is form-encoded rather than JSON. An empty string is allowed. grant_type, client_id, client_secret, client_assertion and client_assertion_type are set by Fireblocks and cannot be overridden. Names are case-sensitive. The whole object must be under 16 KB. Values are write-only; responses return only the parameter names. On update this merges key by key rather than replacing — see WebhookOAuthCustomBodyParamsUpdate.

Show child attributes

Example:

{ "scope": "payments.read payments.write" }

customHeaders

object | null

Extra HTTP headers for the token request to your authorization server — not for the webhook delivery, which has its own separate customHeaders. A gateway API key is the usual case. Applies to every authentication method. Values must be strings; an empty string is allowed. Names are matched case-insensitively, so two names differing only in case are a duplicate. Names are stored and returned lowercased, so X-Api-Key comes back as x-api-key. Content-Type, Authorization, Content-Length and Host are set by Fireblocks and cannot be overridden. The whole object must be under 16 KB. Values are write-only; responses return only the header names. On update this merges name by name rather than replacing — see WebhookOAuthCustomHeadersUpdate.

Show child attributes

Example:

{ "x-api-key": "gateway-key" }

mtlsClientSignedCert

string

PEM-encoded client certificate for mTLS when fetching tokens. Must be a valid X.509 certificate inside its validity window.

Example:

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

Response

created the OAuth credentials successfully

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.createWebhookOAuth(webhooksV2ApiCreateWebhookOAuthRequest);

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

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

fetch('https://api.fireblocks.io/v1/webhooks_settings/oauth', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Production treasury gateway',
    'clientId' => 'my-client-id',
    'clientSecret' => 'my-client-secret',
    'url' => 'https://auth.example.com/oauth/token',
    'authMethod' => 'client_secret_basic',
    'customJwtClaims' => [
        'aud' => 'https://auth.example.com',
        'email_verified' => true
    ],
    'customBodyParams' => [
        'scope' => 'payments.read payments.write'
    ],
    'customHeaders' => [
        'x-api-key' => 'gateway-key'
    ],
    '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"

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

	req, _ := http.NewRequest("POST", 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")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Production treasury gateway\",\n  \"clientId\": \"my-client-id\",\n  \"clientSecret\": \"my-client-secret\",\n  \"url\": \"https://auth.example.com/oauth/token\",\n  \"authMethod\": \"client_secret_basic\",\n  \"customJwtClaims\": {\n    \"aud\": \"https://auth.example.com\",\n    \"email_verified\": true\n  },\n  \"customBodyParams\": {\n    \"scope\": \"payments.read payments.write\"\n  },\n  \"customHeaders\": {\n    \"x-api-key\": \"gateway-key\"\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

Headers

Body

Response