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.

The created secret is nested under signingSecret.

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 \
  -u "$MOOV_API_KEY_ID:$MOOV_API_KEY_SECRET" \
  -H "X-Moov-Version: v2026.10.00" \
  -H "X-Idempotency-Key: $(uuidgen)"
Responses
201 400 401 403 409
The resource was successfully created.
{
  "signingSecret": {
    "createdOn": "2026-08-31T12:00:00Z",
    "revokedOn": null,
    "secret": "c2VjcmV0LXZhbHVlLWZvci1leGFtcGxlLW9ubHk",
    "secretID": "sec_01HF5J9ZKQT4RXP8M2VYBN3D"
  }
}
Malformed request: the body or headers failed validation.
Response body application/problem+json
RFC 9457 Problem Details error body, served as application/problem+json. From v2026.10.00, every error response that has a body uses this schema.

type

string required
URI that tells you which problem occurred. Branch on this value; it never changes. Moov problem types look like https://api.moov.money/errors#<code> (for example invalid-request, idempotency-key-reused, or idempotency-request-in-progress). Treat the value as an opaque constant and do not fetch it. about:blank means the HTTP status code says everything there is to know.

title

string required
Short human-readable name of the problem type. Fixed per type; defaults to the HTTP status text.

status

integer<int32> required
The HTTP status code of this response.

detail

string
Human-readable explanation of this specific occurrence.

instance

string
URI reference that identifies this specific occurrence.

errors

array<object>
The request-body fields that failed validation. Present on validation errors only.
Show child attributes

errors[]

pointer

string required
RFC 6901 JSON Pointer to the field, using the public JSON field names. If the field is missing, the pointer shows where it belongs.

detail

string required
What is wrong with the field.
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.
Response body application/problem+json
RFC 9457 Problem Details error body, served as application/problem+json. From v2026.10.00, every error response that has a body uses this schema.

type

string required
URI that tells you which problem occurred. Branch on this value; it never changes. Moov problem types look like https://api.moov.money/errors#<code> (for example invalid-request, idempotency-key-reused, or idempotency-request-in-progress). Treat the value as an opaque constant and do not fetch it. about:blank means the HTTP status code says everything there is to know.

title

string required
Short human-readable name of the problem type. Fixed per type; defaults to the HTTP status text.

status

integer<int32> required
The HTTP status code of this response.

detail

string
Human-readable explanation of this specific occurrence.

instance

string
URI reference that identifies this specific occurrence.

errors

array<object>
The request-body fields that failed validation. Present on validation errors only.
Show child attributes

errors[]

pointer

string required
RFC 6901 JSON Pointer to the field, using the public JSON field names. If the field is missing, the pointer shows where it belongs.

detail

string required
What is wrong with the field.

Headers

X-Moov-Version

string
Set this header to the API version being targeted (e.g. v2026.10.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

secretID

string required
Unique identifier for the signing secret.

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
Base64url-encoded (RFC 4648 ยง5, no padding) 256-bit plaintext shared secret. Returned exactly once on creation; never exposed again. Base64url-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.