To begin your integration with Klarna, the first step is to obtain your API credentials. Once your account is set up by Klarna, you will receive your initial API key through a secure link.

With your initial API key from Klarna, you can create new API keys and Client IDs through the Partner Management API. Here's how these credentials function:

• API keys: Are used to authenticate server-side REST API requests towards Klarna. In addition, Klarna may use them to identify the source account.

Structure: klarna_<live|test>_api_<random>

• Client IDs: Are used to authenticate client-side interactions towards Klarna’s SDK. Due to the nature of frontend authentication, client keys require domain registration.

Structure: klarna_<live|test>_client_<random>

Credential management is fully under the control of the Acquiring Partner, who can create and manage credentials for different services. This autonomy enhances security by enabling automatic credential rotation, reducing the need for manual updating by Klarna.

To minimize risk in the event of a security breach, assign unique credentials to each service and use the description field to clearly define each credential's purpose. This approach simplifies credential management and ensures that if one credential is compromised or needs to be deactivated, it won’t affect the others, maintaining uninterrupted operation across your integration.

Other recommended practices:

• Never store credentials in plaintext.
• Implement strict access controls to limit credential exposure.
• Regularly rotate credentials.
• Immediately revoke and notify Klarna support if credentials are compromised.

Credentials can be managed for either live or test environments and are specific to client-side or server-side actions. When creating credentials, you can add a description to specify their use, which can be verified via the List Credentials API.

For rotating API-keys, it's recommended to support multiple credentials during the transition. The steps for key rotation involve:

1. Use the Create Credential API-key to request new API-key credentials
2. Transition your service from existing API-key to the new API-key.
3. Validate the new API-key have been correctly implemented.
4. Use the Disable Credential API-key to permanently disable the affected API-key.

Client IDs are not secret since they are available publicly so there is generally not a need to rotate them. If the need arises, e.g. to discourage abusive use, the following API endpoints are used to create new ones, the same as for API-keys.

Consult the API reference for a complete description of the request body parameters, and Security for more information about securely integrating Klarna.

Mutual Transport Layer Security (mTLS) is an enhanced communication security mechanism that adds extra layers of protection to make it more difficult for attackers to misuse leaked credentials. It ensures that both the client and server authenticate each other, making the communication more secure.

Klarna requires acquiring partners to implement mTLS to ensure the security of Partner integrations. For all other account types, it may be enabled manually by Klarna on request.

• Create and Store Your Private Key using elliptic curve cryptography with the prime256v1 specification.
  
  • Example: creation command for certificate key
  

openssl ecparam -genkey -name prime256v1 -out my-key-file.pem

• Create a certificate signing request (CSR)
  
  • The Common Name (CN) in the CSR should be the last part of your account ID.
  
  • For example, if your account ID is krn:partner:global:account:live:LYABCDEI, the CN should be LYABCDEI.
  
  • Example: creating a certificate signing request (CSR)
  

openssl req -new -key my-key-file.pem -out csr.pem -subj "/CN=LYABCDEI"

• Use your API key to create a certificate using the "createCredentialsClientCertificate" API operation, documented here, the certificate will be returned in the API-response. Now the certificate is in an enabled state, but not enforced. This is done so that the status of the mTLS configuration can be verified safely before enforcing access.
• Store the generated certificate and configure to be used in your runtime environment together with the private key.
  
  • Example using curl which will list the newly created certificate
  

curl  --cert certificate.pem --key private-key.pem  -H "Authorization: Basic $API_TOKEN" https://api-global.klarna.com/v2/account/integration/credentials/client-certificate

• After the certificate has been returned, the APIs will return a response header including the status of the MTLS verification. The header returned is Klarna-Mtls-Verification-Status and the value is one of “NOT_PRESENT”, “VALID” and “INVALID” so that the configuration can be verified before enforcing.
• When the integration has been setup and requests returns “VALID” status it's time to enforce access security. Please contact the Klarna account team and communicate from which time mTLS should be enforced
• At the activation time the mTLS client certificate will be verified on all API-requests and the status header will stop being returned.

Important notes

• CSR Requirements: The CSR should only include the CN and no extra attributes.
• Certificate Validity: The issued certificate is valid for 3 years. You need to monitor its expiration and initiate the renewal process in advance.
• Multiple Certificates: You can have up to 10 active certificates at a time.
• Revoking Certificates: Before revoking an active certificate, ensure a new certificate is issued and installed. Use the partner API Revoke Client Certificate to revoke the certificate.

Certificate rotation process

1. Issue a New Certificate following the steps above to create and submit a CSR.
2. Install and Test the New Certificate, ensuring the new certificate works correctly.
3. Revoke the Old Certificate, using the partner API to revoke the old certificate after confirming the new one is functioning.
4. By following these steps, you can ensure a secure and smooth setup of mTLS for your Klarna account.

To enhance the security of API integrations, Klarna supports IP address restriction, allowing partners to define an allow-list of IP addresses from which requests are permitted. All requests originating from outside the defined list will be blocked.

Partners can specify up to 100 IP addresses, including both IPv4 and IPv6 formats, as part of this restriction policy. When enabled, Klarna validates every incoming API request against the configured IP list.

• Reach out to the Klarna partner account team to request activation of the IP address restriction and provide the list of public IP addresses to be authorized for API access.
• First Klarna enables the feature in validation mode, and your API responses will include the HTTP header Klarna-Ip-Validation-Status with one of the values: ALLOWED, DENIED, or INVALID.
  
  • ALLOWED - The request came from a applowed IP address. No action needed.
  
  • DENIED - The request came from a non-whitelisted IP. Verify the source IP is correct and included in your submitted list.
  
  • INVALID - A technical error occurred during IP validation. Contact Klarna partner account team for assistance.
  
• After confirming that all expected requests return Klarna-Ip-Validation-Status: ALLOWED, notify Klarna partner account team to schedule enforcement.
• Once enforcement is active:
  
  • Requests from non-allow-listed IPs will be blocked.
  
  • The Klarna-Ip-Validation-Status header will no longer be included in responses.
  

• Maintain an accurate and current list of all outbound IPs used by your systems.
• Notify Klarna promptly of any infrastructure or network changes that may affect IP origins.
• Avoid using dynamic or shared NAT IPs that may change over time.