Replace the key-encryption key

PUT 
/v1/encryption-targets/:purpose

Registers a different key-encryption key (KEK) for this purpose after onboarding. The first KEK is registered during onboarding (POST /v1/onboarding-cases/{case_id}/encryption-targets); use this operation to replace it later.

Required scope: connector:encryption-targets:update.

Request. data.type is encryption-targets; backend_class is AWS_KMS; backend_ref is the KMS key ARN arn:aws:kms:{region}:{account_id}:key/{key_id} (12-digit account id; alias ARNs are rejected). A blank or malformed backend_ref returns 400 with source.pointer /data/attributes/backend_ref.

Proof of use. Before the new key is accepted, the platform generates a data key under it, wraps it and unwraps it again, exercising kms:GenerateDataKey, kms:Encrypt and kms:Decrypt. A key whose policy does not grant all three to the platform runtime role, or that is unknown or disabled, is rejected: the call returns an error (typically 400) and the operation is recorded as FAILED. If KMS is temporarily unreachable the call returns 503.

Result. On success the call returns 202 with the operation that recorded the new key; read it with GET /v1/operations/{operation_id}.

Idempotency. The Idempotency-Key header is required (400 without it). Replaying the same key with the same body returns the original 202 document; the same key with a different body returns 409 IDEMPOTENCY_CONFLICT, and a replay while the first request is still running returns 409 IDEMPOTENCY_PENDING.

Request

Responses

202

Request accepted for asynchronous processing. An operation has been created to track it; data.id is its operation_id. Acceptance is not success: the request can still be rejected, fail or be cancelled. Poll GET /v1/operations/{operation_id} until the operation reaches a terminal state. Replaying the same Idempotency-Key with the same body returns this same document again.

400

The request is malformed: invalid JSON syntax, an invalid path or query parameter, a missing required header such as Idempotency-Key, or a single field that fails its own format rule. Fix the request before retrying; retrying it unchanged fails again.

401

The bearer token is missing, malformed, expired, signed by an unknown key, or was not issued by the platform IAM for the Lyriq Connector. Obtain a new token and retry. See the Authentication section.

403

The token is valid but may not perform this request: it lacks the required scope, has no bank membership, needs an x-dan-bank-id header to choose between several memberships, names a bank in x-dan-bank-id it has no membership for, or the caller's bank is suspended or terminated. A new token with the same configuration fails the same way. See the Authentication section.

409

The request conflicts with an earlier request or with the current state of the target: an Idempotency-Key reused with a different body (IDEMPOTENCY_CONFLICT), a request with the same key still in progress (IDEMPOTENCY_PENDING), or a target resource in a state that does not allow the request (STATE_CONFLICT).

422

The request is well-formed JSON but cannot be processed: the body does not match the expected shape (a missing or unknown member, a wrong type, or a wrong data.type), or it breaks a business or cross-field rule. Correct the request before retrying.

429

The request was refused because a rate limit was reached (code RATE_LIMITED). No Retry-After header is sent; retry with exponential backoff.

503

The request could not be served right now. Either the network is not fully operational (OUTBOUND_HALTED or READ_ONLY: mutations are refused while read endpoints keep working; OPERATIONAL_STATE_UNKNOWN: the state could not be determined), or a platform dependency is temporarily unavailable. No Retry-After header is sent; retry later with backoff. When retrying a mutation, reuse the same Idempotency-Key and body.