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
| Environment | Certificate-add endpoint |
|---|---|
| Production | POST https://tpp.openbanking.prod.lunar.tech/tpp/{clientId}/certificates |
| Sandbox | POST 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_ALLOWEDnaming the role. A certificate asserting onlyPSP_AI, for example, cannot be added to a client registered for bothPSP_AIandPSP_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/certificatesTroubleshooting
Errors carry a machine-readable code alongside the HTTP status. See Error responses for the response envelope and the complete list of codes.
| Status | Code | Description |
|---|---|---|
400 Bad Request | INVALID_REQUEST or INVALID_CERTIFICATE_CHAIN | The 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 Forbidden | CERTIFICATE_VALIDATION_FAILED | The chain is not a valid, trusted eIDAS QWAC. |
403 Forbidden | ROLE_NOT_ALLOWED | The certificate does not assert the PSD2 roles your client is registered for. |
403 Forbidden | CLIENT_INACTIVE | The client has been deactivated. |
404 Not Found | CLIENT_NOT_FOUND | No 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/verifyThis endpoint requires mTLS with your eIDAS certificate. A 200 OK response indicates that the certificate is valid and properly configured.