Skip to Content
RegistrationClient ManagementAdd or rotate a certificate

Add or rotate a certificate

Add a certificate to an existing TPP registration to support certificate rotation or multiple certificates.

Before making this request, obtain a management access token for the client you are changing. The request also requires mTLS with your existing valid eIDAS QWAC and private key.

Endpoints

EnvironmentCertificate-add endpoint
ProductionPOST https://tpp.openbanking.prod.lunar.tech/tpp/{clientId}/certificates
SandboxPOST https://tpp.openbanking-sandbox.prod.lunar.tech/tpp/{clientId}/certificates

Send the bearer token as Authorization: Bearer <access-token>, present the existing QWAC over mTLS, and place the new certificate chain in the JSON request body.

Certificate requirements

  • Use a PEM-encoded certificate chain from the leaf certificate to the root CA.
  • The new certificate must be a valid eIDAS QWAC.
  • It must assert at least the PSD2 roles your client is registered for. Additional roles are allowed; a missing role is rejected with ROLE_NOT_ALLOWED naming the role. A certificate asserting only PSP_AI, for example, cannot be added to a client registered for both PSP_AI and PSP_PI.
  • The certificate must not be expired.

This is the opposite direction from registration, where the roles you request must be a subset of the roles asserted by your certificate. See Register as a third party provider.

Request format

{ "certificate": "-----BEGIN CERTIFICATE-----\nMIIE...leaf certificate...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIF...intermediate CA...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIG...root CA...\n-----END CERTIFICATE-----", "updateDisplayName": true }

Set updateDisplayName to true to update the consent display name from the Organization attribute in the added chain’s leaf QWAC. It defaults to false.

Example

CERT_JSON=$(cat leaf.pem intermediate.pem root.pem | jq -R -s .) curl \ -X POST \ -H "Authorization: Bearer your-access-token" \ -H "Content-Type: application/json" \ --data "{\"certificate\": $CERT_JSON, \"updateDisplayName\": true}" \ --cert client.pem \ --key client.key \ https://tpp.openbanking.prod.lunar.tech/tpp/your-client-id/certificates

Troubleshooting

Errors carry a machine-readable code alongside the HTTP status. See Error responses for the response envelope and the complete list of codes.

StatusCodeDescription
400 Bad RequestINVALID_REQUEST or INVALID_CERTIFICATE_CHAINThe request body is malformed, or the certificate value is not a complete PEM chain from leaf to root.
401 Unauthorized—The bearer token is missing or invalid, or mTLS certificate authentication failed.
403 ForbiddenCERTIFICATE_VALIDATION_FAILEDThe chain is not a valid, trusted eIDAS QWAC.
403 ForbiddenROLE_NOT_ALLOWEDThe certificate does not assert the PSD2 roles your client is registered for.
403 ForbiddenCLIENT_INACTIVEThe client has been deactivated.
404 Not FoundCLIENT_NOT_FOUNDNo client matches the {clientId} in the path, or it differs from your token’s subject. Ownership is determined by the token subject, not by the certificate you present.

Verify your certificate

Verify that your eIDAS certificate is correctly configured when troubleshooting mTLS connectivity:

GET https://api.openbanking.prod.lunar.app/tpp/verify

This endpoint requires mTLS with your eIDAS certificate. A 200 OK response indicates that the certificate is valid and properly configured.

Last updated on