Enrollment

Enrollment is how you turn a bank-issued, one-time enrollment file into the two certificates you'll use for every subsequent API call.

1. The bank issues you an enrollment file

   The bank generates a password-protected enrollment file out-of-band and shares it (and the password, separately) with you. It contains an encrypted, time-limited enrollment token scoped to your enrollmentId, clientApplicationId, environment, and the exact CSR-upload URL you must call.

2. You generate two certificate signing requests (CSRs)

   Generate two separate key pairs and CSRs locally — your private keys never leave your systems:

   • mTLS client CSR — RSA (3072–8192 bits, exponent 65537) or ECDSA (P-256/P-384)
   • Document-signing CSR — RSA only (3072–8192 bits, exponent 65537); ECDSA is not accepted for the signing certificate

3. Upload the CSRs

   Call the CSR upload endpoint with the enrollment token from step 1 as a bearer token, and your enrollmentId as a query parameter:

   POST /csr?enrollmentId={enrollmentId}
   Authorization: Bearer {enrollmentToken}
   Content-Type: application/json
   
   {
     "clientApplicationId": "{clientApplicationId}",
     "mtlsClientCsrPem": "-----BEGIN CERTIFICATE REQUEST-----...",
     "signingCsrPem": "-----BEGIN CERTIFICATE REQUEST-----...",
     "environment": "Production"
   }

   The environment value must match the environment embedded in your enrollment token.

4. Receive your certificates

   On success, the API returns both issued certificates as PEM:

   {
     "mtlsCertificatePem": "-----BEGIN CERTIFICATE-----...",
     "signingCertificatePem": "-----BEGIN CERTIFICATE-----..."
   }

   Combine each returned certificate with the private key you generated in step 2 (matching the CSR you sent) to get a usable certificate + key pair. Certificates are valid for one year from issuance.

Error responses to handle

Status	Meaning
401 Unauthorized	Missing, malformed, or invalid/expired enrollment token.
400 Bad Request	Missing enrollmentId, clientApplicationId, or a CSR field.
422 Unprocessable Entity	A CSR failed validation (bad key size, unsupported algorithm, malformed PEM).