API References

Register a webhook signing key

post
https://app.bitgo-test.com/api/policy/v1/enterprises//webhooks/keys

Registers a new webhook signing key for an enterprise. The key can be provided inline via a JWKS payload or referenced via a JWKS URI.

Key ID selection: The keyId (derived from the kid field in the JWK, or supplied explicitly for JWKS URI registrations) must be unique within the enterprise. Once a keyId is used — even if the key is later revoked — it is permanently tombstoned and cannot be reused. Plan for this by choosing a stable, unique keyId from the start (e.g. my-key-v2).

Recommended rotation workflow:

  1. Register the new key under a new keyId (e.g. my-key-v2).
  2. Update your service configuration to sign webhooks with the new key.
  3. Revoke the old key only after you have confirmed the new key is working.

Authorization: Caller must be an admin of the specified enterprise.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The enterprise ID.

Body Params
jwks
object

Inline JWKS payload containing the public key(s). Mutually exclusive with jwksUri. The kid field inside the JWK object becomes the keyId for this registration. Choose a stable, unique kid value (e.g. my-key-v2) because once a keyId is revoked it is permanently tombstoned and cannot be reused.

string

URI pointing to a hosted JWKS endpoint. Mutually exclusive with jwks.

string
length ≤ 255

Customer-provided key identifier. Required when registering via jwksUri (must match the kid in your JWKS endpoint). Optional when registering inline JWKS (derived from the JWK kid field if not provided).

Permanent restriction: Once a keyId is registered under an enterprise — even if the key is later revoked — the keyId is permanently tombstoned and cannot be reused. Attempting to re-register the same keyId returns a 400 error. Choose stable, unique values (e.g. my-key-v2) to avoid needing to update secrets and configuration after key rotation.

string

Human-readable name for the key.

Headers
string
required

OTP code for verification. Required for webhook key management operations.

Responses

Updated about 8 hours ago

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 8 hours ago