Create signing secret

POST
/providers/{providerID}/signing-secrets

Create a signing secret: the shared 256-bit key that encrypts ledger traffic between Moov Money and you. Moov Money wraps each ledger request JWE with this key, and you encrypt your response JWE with it (A256KW + A256GCM). The plaintext secret is returned exactly once, in this response, and is never retrievable again.

From v2026.10.00 the created secret is nested under signingSecret. Before that the 201 body is the secret object itself.

From v2026.10.00 send an X-Idempotency-Key header. The server echoes that header on the response. The key is retained for 24 hours after the create completes. Replaying the same key within that window returns a 409 with error code idempotency-key-reused and never includes the plaintext. After the window, the same key creates a new secret and returns its plaintext exactly once. The earlier secret stays active until you revoke it. Returns a 409 with error code idempotency-request-in-progress when a request with this key is still running. Returns 400 when the header is missing or malformed.

Multiple active secrets are supported at the same time, so you can rotate keys without downtime: create the new secret, deploy it, then revoke the old one.

Auth: API key or bearer token. The providerID in the path must be your account.

Request
cURL
curl -X POST https://api.moov.money/providers/{providerID}/signing-secrets
Responses
201 400 401 403 409
The resource was successfully created.
{
  "signingSecret": {
    "createdOn": "2026-08-31T12:00:00Z",
    "secret": "c2VjcmV0LXZhbHVlLWZvci1leGFtcGxlLW9ubHk",
    "secretID": "sec_01HF5J9ZKQT4RXP8M2VYBN3D"
  }
}
Malformed request: the body or headers failed validation.
Authentication missing, invalid, or insufficient.
Authentication present but the action is forbidden for this principal/claim.
The request conflicts with the current state of the target resource.

Headers

X-Moov-Version

string
Set this header to the API version being targeted (e.g. v2026.07.00). When omitted, the server applies its default version.

X-Idempotency-Key

string required
Client-supplied key that identifies this create request, 1 to 255 characters. Send the header once. Retries with the same key are processed once for 24 hours after the request completes.

Path parameters

providerID

string required
Your provider account ID.

Response

Response envelope for create signing secret.

signingSecret

object required
The created signing secret, including the plaintext secret.
Show child attributes

signingSecret

createdOn

string<date-time> required
When the secret was created.

revokedOn

string<date-time> | null required
When the secret was revoked, or null while active.

secret

string required
Base64-encoded 256-bit plaintext shared secret. Returned exactly once on creation; never exposed again. Base64-decode it to the raw 32 bytes, then use it as the A256KW wrapping key for the ledger request and response JWEs (A256KW + A256GCM). See the contract introduction for the full envelope description.

secretID

string required
Unique identifier for the signing secret.