Skip to main content
POST
Rotate the callback signing secret for an External Application
This is not the client secret. client_secret authenticates the app to Forge; the callback signing secret lets your receiver verify a dispatch callback came from Forge. Rotating one does not affect the other.
The secret is minted lazily the first time the app uses a dispatch callback. Rotation is immediate and total: there is no overlap window, so deliveries signed after this call use the new key. Update the receiver first. 404 if no such app. 409 if the app is deactivated — reviving a deactivated app by rotating a key is not a supported path.

The secret is shown once

The response carries the secret exactly once. Forge keeps only an encrypted copy of the callback signing secret, and it never stores this response for Idempotency-Key replay. A repeat with the same key and body answers 200 with only the app’s data.id (id-only replay), without the secret, and does not run again — no second rotation happens. A lost secret cannot be recovered: rotate again. An app you may not manage — one whose management home your grants do not cover — answers 404 resource_missing.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

externalAppId
string
required

Response

Callback signing secret rotated. Response includes the one-time callbackSigningSecret. A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only data.id (IdOnlyReplay, Idempotency-Replay-Disclosure: id-only).

data
object
required
meta
object
required