Register the bank's key-encryption key for an onboarding case

POST 
/v1/onboarding-cases/:case_id/encryption-targets

Registers the bank-held key-encryption key. The key stays in the bank's AWS account; only its key ARN is recorded and no key material is accepted. The target is created with verification_state: PENDING; call POST .../encryption-targets/{target_id}/verify to prove the platform can use the key before you submit.

Before verifying, grant the platform's runtime role kms:GenerateDataKey, kms:Encrypt and kms:Decrypt on the key (see the Encryption Targets tag). As an alternative, POST .../key-generation-jobs with ENCRYPT_TRANSFER_SOURCE_MESSAGE creates, registers and verifies the key for you.

Required scope: connector:onboarding:artifacts:write.

Allowed states: AWAITING_BANK_ADMIN, BANK_CONFIGURING, NEEDS_CHANGES (otherwise 409). The first edit moves AWAITING_BANK_ADMIN to BANK_CONFIGURING.

Fields (all in data.attributes):

• purpose (required): ENCRYPT_TRANSFER_SOURCE_MESSAGE. One target per purpose; a second one returns 409.
• backend_class (required): AWS_KMS.
• backend_ref (required): a KMS key ARN, arn:aws:kms:{region}:{account_id}:key/{key_id}, with a 12-digit account id. Alias ARNs are rejected, because a wrapped data key can only be unwrapped by the exact key that wrapped it. Surrounding whitespace is trimmed. A blank value returns 400 MISSING_FIELD; a malformed ARN returns 400 INVALID_FIELD_FORMAT.

Ownership check. The platform checks the ARN against the keys it has generated. A key the platform generated for another bank or case is rejected with 403 BANK_SCOPE_MISMATCH. This check needs the platform key service; if it is unavailable the call returns 503.

No Idempotency-Key is used. Repeating a successful request returns 409.

Request

Responses

201

Encryption target recorded with verification_state PENDING.

400

backend_ref is blank or is not a KMS key ARN.

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.

404

The resource does not exist, or it belongs to another bank. The Lyriq Connector does not distinguish the two cases, so resources of other banks are never disclosed.

409

The case is not editable, or a target already exists for this purpose or key ARN.

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.

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.