--- title: "Create OAuth credentials" method: POST path: "/webhooks_settings/oauth" tags: ["Webhooks V2"] --- # Create OAuth credentials `POST /webhooks_settings/oauth` ## Request - Base URL: `https://api.fireblocks.io/v1` - URL: `https://api.fireblocks.io/v1/webhooks_settings/oauth` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a reusable OAuth 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. The client secret is write-only and is never returned. **Endpoint Permissions:** Owner, Admin, Non-Signing Admin. ## Headers - `Idempotency-Key` string ## Request body - CreateWebhookOauthRequest: 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. - `clientId` string, required: OAuth client ID used to authenticate with the token endpoint. - `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. - `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. - `authMethod` string: 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`. - `customJwtClaims` WebhookOauthCustomJwtClaims, nullable: 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`. - `customBodyParams` WebhookOauthCustomBodyParams, nullable: 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`. - `customHeaders` WebhookOauthCustomHeaders, nullable: 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. 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`, `Content-Length` and `Host` are set by Fireblocks and cannot be overridden. `Authorization` can be set with `client_secret_post` or `client_secret_jwt`, which send the credentials in the body — useful when your token endpoint sits behind a gateway. It is rejected with `client_secret_basic`, which sends the credentials in that header. Values have no length limit of their own; the whole object must be under 16 KB when serialized as UTF-8. Values are write-only; responses return only the header names. On update this merges name by name rather than replacing — see `WebhookOauthCustomHeadersUpdate`. - `webhookMtlsId` string, uuid, nullable: The id of the mTLS configuration presented to the token endpoint, from `/v1/webhooks_settings/mtls`. It can be the same configuration a webhook uses, so one certificate, signed from `GET /v1/webhooks_settings/mtls_csr`, serves both the token endpoint and the receiver. Omit, or send `null`, for a token request without mTLS. 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 `201` created the OAuth credentials successfully - 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)