Client Management

Once registered as a third party provider (TPP), you can manage your client configuration using the client management APIs. These APIs allow you to view client details, update redirect URIs, and add certificates.

Prerequisites

For all client management operations, you need:

• A valid eIDAS certificate for certificate-based authentication
• Your OAuth 2.0 clientId and clientSecret obtained during registration

Authentication

All client management endpoints require an Authorization header with a valid access token.

Getting an Access Token

To access client management APIs, you need to obtain an access token using the OAuth2 client credentials flow. This requires the clientId and clientSecret you received during TPP registration.

Request Details

• Grant Type: client_credentials
• Authentication Method: HTTP Basic Authentication (client_secret_basic)
• Content Type: application/x-www-form-urlencoded

Example Request

# Encode your credentials for Basic auth
CREDENTIALS=$(echo -n "your-client-id:your-client-secret" | base64)
 
curl \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $CREDENTIALS" \
  -X POST \
  --cert client.pem \
  --key client.key \
  -d "grant_type=client_credentials" \
  https://auth.openbanking.prod.lunar.app/oauth2/token

Response

{
  "access_token": "ey...",
  "token_type": "Bearer",
  "expires_in": 3600
}

The access token can then be used in the Authorization header as Bearer your-access-token for subsequent API calls.

Available Operations

Get Client Details

Retrieve detailed information about your registered TPP client.

Endpoint: GET /tpp/{clientId}

Response includes:

• Client name and ID
• Assigned roles (PSP_AI, PSP_PI)
• Configured redirect URIs
• Associated certificate chains with details

Example

curl \
  -H "Authorization: Bearer your-access-token" \
  --cert client.pem \
  --key client.key \
  https://tpp.openbanking.prod.lunar.tech/tpp/33a2b623-8011-41bc-b45c-f034b01dbc1c

Response

{
  "name": "mycompany",
  "clientId": "33a2b623-8011-41bc-b45c-f034b01dbc1c",
  "roles": ["PSP_AI", "PSP_PI"],
  "redirectUris": ["https://mycompany.com/oauth2/callback"],
  "certificateChains": [
    {
      "certificates": [
        {
          "subject": "CN=MyCompany,O=MyCompany Ltd,C=DK",
          "subjectKeyId": "AA:BB:CC:DD:EE:FF:11:22:33:44",
          "issuer": "CN=CA,O=Certificate Authority,C=DK",
          "serialNumber": "12345678",
          "notBefore": "2023-01-01T00:00:00Z",
          "notAfter": "2024-12-31T23:59:59Z"
        }
      ]
    }
  ]
}

Update Redirect URIs

Modify the redirect URIs for your registered client. This operation completely replaces the existing redirect URIs with the new ones provided.

Endpoint: PUT /tpp/{clientId}/redirect-uris

Important Considerations

• Complete Replacement: The PUT operation replaces all existing redirect URIs
• Uniqueness: Duplicate URIs in the array are not allowed
• Minimum Required: At least one redirect URI must be provided

Request Format

{
  "redirectUris": [
    "https://mycompany.com/oauth2/callback",
    "https://staging.mycompany.com/oauth2/callback"
  ]
}

Example

curl \
  -X PUT \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  --data '{"redirectUris":["https://mycompany.com/oauth2/callback","https://staging.mycompany.com/oauth2/callback"]}' \
  --cert client.pem \
  --key client.key \
  https://tpp.openbanking.prod.lunar.tech/tpp/33a2b623-8011-41bc-b45c-f034b01dbc1c/redirect-uris

Common Errors

Add Certificate

Add a new certificate to your existing TPP registration. This allows you to use multiple certificates for the same client, which is useful for certificate rotation or supporting multiple environments.

Endpoint: POST /tpp/{clientId}/certificates

Certificate Requirements

• Format: PEM-encoded certificate chain
• Chain Completeness: Must include complete chain from leaf certificate to root CA
• eIDAS Compliance: Certificate must be a valid eIDAS QWAC (Qualified Website Authentication Certificate)
• Role Validation: Certificate roles must match or be a subset of your registered TPP roles

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-----"
}

Preparing the Certificate Chain

1. Obtain Certificate: Get your eIDAS QWAC from a qualified certificate authority
2. Build Chain: Combine leaf, intermediate, and root certificates
3. Format: Ensure proper PEM formatting with line breaks preserved
4. Validate: Verify the certificate chain is complete and valid

Example with File

# Prepare certificate chain from separate files to be included in the json payload
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}" \
  --cert client.pem \
  --key client.key \
  https://tpp.openbanking.prod.lunar.tech/tpp/33a2b623-8011-41bc-b45c-f034b01dbc1c/certificates

Validation Process

When you add a certificate, Lunar validates:

1. Certificate Format: Valid PEM encoding and structure
2. Chain Integrity: Complete chain from leaf to trusted root
3. eIDAS Compliance: Valid QWAC with appropriate OIDs
4. Role Compatibility: Certificate roles match your TPP registration
5. Expiration: Certificate is not expired

Common Errors

Related Documentation

• Register as a third party provider - Initial TPP registration
• Security model - eIDAS certificate requirements