Set up IP address restrictions

Enhance API security by enabling IP address restrictions in Klarna, allowing only approved IPs to access the integration. Start with reporting mode and move to full enforcement to block unauthorized traffic.

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 CIDR-blocks, each possibly covering multiple IPs, 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.

Setup IP address restrictions

Enhance API security by restricting access to the Klarna API integration to approved source IP ranges. Start in reporting mode to validate the configuration, then enable enforcement to block traffic from IPs that are not on the allowlist.

This article is intended for Partners integrating with Klarna using Klarna API integration.

Overview

Scope: Account-level IP allowlist for inbound API traffic to Klarna Network v2.
Modes:
- NOT_ENABLED: The IP restrictions feature is not enabled.
- REPORTING: Requests are allowed, and responses include the Klarna-Ip-Validation-Status header.
- ENFORCED: Requests from IPs not on the allowlist are blocked. The header is no longer included.
Limits: Up to 100 CIDR entries (IPv4 and/or IPv6) per Klarna account.
Propagation: Changes and enforcement take up to 5 minutes to take effect.

How it works

Partners configure an account-level allowlist of source IP ranges in CIDR notation.
While in reporting mode, every API response includes Klarna-Ip-Validation-Status with one of the following values:
- ALLOWED: The request originated from an IP on the allowlist.
- DENIED: The request originated from an IP that is not on the allowlist.
- INVALID: A technical error occurred during IP validation. Contact the standard Partner support channel.
After confirming the allowlist is correct, enable enforcement so requests from IPs not on the allowlist are blocked.

Prerequisites

API credentials authorized to manage account integration settings.
A complete and accurate list of the Partner's systems' public, egress IPs (both IPv4 and IPv6 as applicable).
A change plan and a maintenance window (recommended), because enforcement begins at the configured time and takes up to 5 minutes to propagate.

Endpoints

IP Allowlist management

PUT /v2/account/integration/inbound-restrictions/ip/allowlist: add or overwrite the allowlist with new values.
POST /v2/account/integration/inbound-restrictions/ip/allowlist: extend the allowlist.
GET /v2/account/integration/inbound-restrictions/ip/allowlist: list all configured allowed IP ranges.

IP restriction enforcement management

PATCH /v2/account/integration/inbound-restrictions/ip: manage IP-restriction enforcement status.
GET /v2/account/integration/inbound-restrictions/ip: read current IP-restriction enforcement status.

Implement IP address restrictions

By default, IP address restrictions are NOT_ENABLED. Start by enabling REPORTING mode explicitly:

Set enforcement_mode to REPORTING via PATCH /v2/account/integration/inbound-restriction/ip.

1) Start in reporting mode

After enabling reporting mode, the responses to the subsequent requests include the Klarna-Ip-Validation-Status header with DENIED status because the IP allowlist is empty.

BASH

1 2 3 4 5 6

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $API_TOKEN" \
  https://api-global.klarna.com/v2/account/integration/inbound-restrictions/ip \
  -d '{"enforcement_mode": "REPORTING"}'

The header can be observed on any API call while in reporting mode. For example:

BASH

1 2 3 4

curl -i -X GET \
  -H "Authorization: Basic $API_TOKEN" \
  https://api-global.klarna.com/v2/account/integration/inbound-restrictions/ip

Example response headers (truncated):

HTTP/1.1 200 OK
Klarna-Ip-Validation-Status: DENIED
...

2) Set the IP allowlist

Send the IP ranges in the request body as a list to the PUT endpoint.

BASH

1 2 3 4 5 6

curl -X PUT \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic $API_TOKEN" \
 https://api-global.klarna.com/v2/account/integration/inbound-restrictions/ip/allowlist \
 -d '["1.0.0.0/8", "1.2.3.0/24", "2001:db8::/48"]'

3) Validate in reporting mode

Exercise the integration from each expected source IP.
Inspect the response header to verify status:
- ALLOWED indicates the source IP is on the allowlist.
- DENIED indicates the source IP is not on the allowlist.
- INVALID indicates a technical error. Contact the standard Partner support channel.

Example response headers (truncated):

HTTP/1.1 200 OK
Klarna-Ip-Validation-Status: ALLOWED
...

3) (Optional) Get the configured IP allowlist

Use the corresponding GET endpoint for /v2/account/integration/inbound-restrictions/ip/allowlist to list all the configured CIDR blocks.

BASH

1 2 3 4

curl -i -X GET \
  -H "Authorization: Basic $API_TOKEN" \
  https://api-global.klarna.com/v2/account/integration/inbound-restrictions/ip/allowlist

4) Enforce the IP allowlist restriction

Once the status from all expected traffic shows ALLOWED, enable enforcement.

Requirements:

The Klarna account must have at least one CIDR entry on the allowlist.
enforced_from is required when enforcement_type is SCHEDULED.
enforced_from must be in ISO 8601 UTC format and a maximum of 3 months in the future.
Enforcement takes up to 5 minutes from the configured time to take effect, even if using "NOW".

Example (schedule a specific time):

BASH

1 2 3 4 5 6

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $API_TOKEN" \
  https://api-global.klarna.com/v2/account/integration/inbound-restrictions/ip \
  -d '{"enforcement_mode": "ENFORCED", "enforcement_type": "SCHEDULED", enforced_from": "2001-01-01T00:00:00Z"}'

Example (enforce immediately):

BASH

1 2 3 4 5 6

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $API_TOKEN" \
  https://api-global.klarna.com/v2/account/integration/inbound-restrictions/ip \
  -d '{"enforcement_mode": "ENFORCED", "enforcement_type": "NOW"}'

Read current status:

BASH

1 2 3 4

curl -X GET \
  -H "Authorization: Basic $API_TOKEN" \
  https://api-global.klarna.com/v2/account/integration/inbound-restrictions/ip

Once enforcement is active (denoted by enforcement_mode set to ENFORCED):

Requests from IPs that are not on the allowlist are blocked.
Klarna-Ip-Validation-Status header is no longer included in responses.

5) Disable enforcement

Setting the enforcement mode to either REPORTING or NOT_ENABLED will disable IP-restriction feature. Changes take up to 5 minutes to propagate.

BASH

1 2 3 4 5 6

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $API_TOKEN" \
  https://api-global.klarna.com/v2/account/integration/inbound-restrictions/ip \
  -d '{"enforcement_mode": "REPORTING"}'

Maintenance of IP allowlist

Append the allow list

Partners might need to add a new IP to the already configured allow list. This can be done using the POST endpoint for /v2/account/integration/inbound-restrictions/ip/allowlist.

The request body is a list of IPs to append to the existing IP list. The response contains the complete list of configured IP allowlist.

Note: This endpoint can be used in either of the modes, ENFORCED or REPORTING.

Example

BASH

1 2 3 4 5 6 7 8

curl -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic $API_TOKEN" \
 https://api-global.klarna.com/v2/account/integration/inbound-restrictions/ip/allowlist \
 -d '["1.2.3.4/24"]'
 
 ["1.0.0.0/8", "1.2.3.0/24", "2001:db8::/48", "1.2.3.4/24"]

Manage IP addresses while enforcement is active

When enforcement is enabled:

New CIDRs can be added to the configured list (via the POST endpoint).
CIDRs cannot be replaced from the configured list.
CIDRs cannot be modified from the configured list.
To remove or replace CIDR-blocks:
1. 4.1.
  Switch to reporting mode (use the PATCH endpoint and change the enforcement_mode to REPORTING) .
2. 4.2.
  Update the allowlist (PUT overwrite or POST append)
3. 4.3.
  Validate in reporting mode until all expected sources show ALLOWED.
4. 4.4.
  Re-enable enforcement.

Using the PATCH endpoint

Endpoint

PATCH /v2/account/integration/inbound-restriction/ip

Overview

The IP endpoint manages the enforcement state of the IP allowlist restrictions through a state machine with three modes: NOT_ENABLED, REPORTING, and ENFORCED. This endpoint allows transitioning between these states with fine-grained control over when enforcement takes effect.

Enforcement modes

NOT_ENABLED: IP allowlist validation is completely disabled. No restrictions are applied, and requests from any IP address are accepted. No status header is returned.

REPORTING: IP allowlist validation is enabled but not enforced. Requests are validated against the allowlist, but violations are only logged. Requests are still accepted. This mode is ideal for testing the allowlist configuration before enforcement.

ENFORCED: IP allowlist validation is fully enforced. Only requests originating from IP addresses in the allowlist are accepted. Requests from unlisted IP addresses are rejected.

Request parameters

Parameter	Type	Required	Description
`enforcement_mode`	string	Yes	Target enforcement mode: NOT_ENABLED, REPORTING, or ENFORCED
`enforcement_type`	string	Conditional	When transitioning to ENFORCED: NOW (immediate) or SCHEDULED (future date)
`enforced_from`	string (ISO 8601)	Conditional	Required when `enforcement_type` is SCHEDULED. Must be a future timestamp

Understanding the `enforcement_mode` Parameter

Critical Concept: the enforcement_mode in the request body represents the intention, the enforcement state the Partner wants to achieve. However, the actual enforcement state in the response depends on the current status (which is set by enforcement_type in the request):

enforcement_type: NOW: transitions immediately. The response enforcement_mode matches the requested mode.
enforcement_type: SCHEDULED: transitions at the specified future time. The response enforcement_mode is REPORTING (transition pending) until the enforced_from timestamp is reached, at which point it becomes ENFORCED.

Example

JAVA

1 2 3 4 5 6 7 8 9 10

// Request: Client intends to enforce IP restrictions
{
  "enforcement_mode": "ENFORCED",
  "enforcement_type": "SCHEDULED",
  "enforced_from": "2099-01-01T00:00:00Z"
}

// Response: Server acknowledges intention but keeps REPORTING until scheduled time
{
  "enforcement_mode": "REPORTING",

This design provides a grace period during which the response status header Klarna-Ip-Validation-Status can be monitored before enforcement activates, ensuring the allowlist is configured correctly.

Enforcement mode transitions

The endpoint provides 9 state transition combinations, each with distinct behavior:

1. NOT_ENABLED → REPORTING

Behavior: Enables IP validation in monitoring mode. All requests are processed normally, but response headers indicate whether the source IP falls within the configured CIDR block/s.

Use Case: First step in enabling IP restrictions. Monitor response headers to verify the status to be ALLOWED.

Example

JAVA

1 2 3 4 5 6 7 8 9 10

// Request
{
  "enforcement_mode": "REPORTING"
}

// Response
{
  "enforcement_mode": "REPORTING"
}

2. REPORTING → ENFORCED

Behavior: Upgrades from monitoring to blocking. RECOMMENDED PATH for production after validating the IP allowlist.

Use Case:

After monitoring response headers in REPORTING mode and confirming the status is ALOWED, upgrade to blocking mode.
To reschedule enforcement time, use enforcement_type with value SCHEDULED. Examples:

Immediate enforcement:

JAVA

1 2 3 4 5 6 7 8 9 10

// Request: Enforce NOW
{
  "enforcement_mode": "ENFORCED",
  "enforcement_type": "NOW"
}

// Response - Starts blocking immediately
{
  "enforcement_mode": "ENFORCED",
  "enforced_from": "<now-timestamp-in-ISO>"

Scheduled enforcement:

JAVA

1 2 3 4 5 6 7 8 9 10

// Request: Scheduled enforcement
{
  "enforcement_mode": "ENFORCED",
  "enforcement_type": "SCHEDULED",
  "enforced_from": "2026-02-01T00:00:00Z"
}

// Response - Continues monitoring until scheduled time
{
  "enforcement_mode": "REPORTING",

3. ENFORCED → REPORTING

Behavior: Stops blocking the requests but continues indicating validation status in response headers. This transition removes any configured enforcement timestamp.

Use Case:

Modify configured CIDR blocks.
Temporary disable while maintaining visibility.

Example:

JAVA

1 2 3 4 5 6 7 8 9 10

// Request
{
  "enforcement_mode": "REPORTING"
}

// Response
{
  "enforcement_mode": "REPORTING"
}

4. ENFORCED → NOT_ENABLED

Behavior: Disable IP restriction feature. Stops blocking the requests and the status header is not included in the response. This transition removes any configured enforcement timestamp.

Use Case: Permanently disabling IP restrictions

Example:

JAVA

1 2 3 4 5 6 7 8 9 10

// Request
{
  "enforcement_mode": "NOT_ENABLED"
}

// Response
{
  "enforcement_mode": "NOT_ENABLED"
}

5. REPORTING → NOT_ENABLED

Behavior: Disables IP restriction feature. Response headers no longer indicate IP validation status. This transition removes any configured enforcement timestamp.

Use Case: Rollback or permanently disable IP restriction feature.

Example:

JAVA

1 2 3 4 5 6 7 8 9 10

// Request
{
  "enforcement_mode": "NOT_ENABLED"
}

// Response
{
  "enforcement_mode": "NOT_ENABLED"
}

6. NOT_ENABLED → ENFORCED

Behavior: This transition is blocked. It is not possible to directly go from NOT_ENABLED to ENFORCED.

Motivation: This action is not allowed in order to make sure that the transition is done safely through the verification of the status headers returned during the reporting mode.

Use the two-step approach here:

1.
First: NOT_ENABLED → REPORTING
2.
Then: REPORTING → ENFORCED

7. NOT_ENABLED → NOT_ENABLED

Behavior: No change. IP validation remains disabled.

Use Case: Confirming current state or idempotent operations.

Example:

JAVA

1 2 3 4 5 6 7 8 9 10

// Request
{
  "enforcement_mode": "NOT_ENABLED"
}

// Response
{
  "enforcement_mode": "NOT_ENABLED"
}

8. REPORTING → REPORTING

Behavior: Maintains current monitoring mode. No functional change.

Use Case: Idempotent operations or confirming current state.

Important Limitation: future enforcement cannot be scheduled while staying in REPORTING mode. To schedule enforcement, transition to ENFORCED mode (see transition #6).

JAVA

1 2 3 4 5 6 7 8 9 10

// Request
{
  "enforcement_mode": "REPORTING"
}

// Response
{
  "enforcement_mode": "REPORTING"
}

Invalid Request:

JAVA

1 2 3 4 5 6 7

// ❌ This will return 400 error
{
  "enforcement_mode": "REPORTING",
  "enforcement_type": "SCHEDULED",
  "enforced_from": "2026-02-01T00:00:00Z"
}

Why This Fails: REPORTING mode means "monitor only, do not block." Scheduling is about when to start blocking, so it requires enforcement_mode: "ENFORCED" to express that intention.

9. ENFORCED → ENFORCED

Behavior: No change. IP validation enforcement is active.

Use Case: Resend the same request with enforcement_type set to NOW

JAVA

1 2 3 4 5 6 7 8 9 10

// Request, enforcement_type accepts only NOW
{
  "enforcement_mode": "ENFORCED",
  "enforcement_type": "NOW"
}

// Response
{
  "enforcement_mode": "ENFORCED",
  "enforced_from": "<timestamp-in-ISO>"

IP address restriction flow diagram

flowchart LR %% ================= LEFT FLOW ================= subgraph ENF["IP Allowlist Enforcement State"] direction TB START((Start)):::tertiaryEntity NOT_ENABLED["NOT_ENABLED (no validation)"]:::tertiaryEntity REPORTING["REPORTING (validate only)"]:::secondaryEntity SCHEDULED["ENFORCEMENT SCHEDULED (pending transition)"]:::primaryEntity ENFORCED["ENFORCED (enforced)"]:::primaryEntity START --> NOT_ENABLED NOT_ENABLED --> REPORTING REPORTING --> ENFORCED REPORTING --> SCHEDULED SCHEDULED --> ENFORCED ENFORCED --> REPORTING REPORTING --> NOT_ENABLED ENFORCED --> NOT_ENABLED end %% ================= RIGHT FLOW ================= subgraph REQ["Request Behaviour"] direction TB R_NE["NOT_ENABLED All requests allowed"]:::tertiaryEntity R_RP["REPORTING Requests allowed Validation only"]:::secondaryEntity R_EF["ENFORCED Only allowlisted IPs allowed"]:::primaryEntity R_NE --> R_RP --> R_EF end %% ================= STATE ↔ BEHAVIOUR MAPPING ================= NOT_ENABLED --- R_NE REPORTING --- R_RP ENFORCED --- R_EF

IP address format requirements

When configuring the allowlist, all entries must meet these requirements.

General requirements

CIDR notation is required (for example, 1.1.1.0/24 or 2001:4860::/32).
Single IPs must use the maximum prefix: /32 for IPv4 or /128 for IPv6.
Examples: 8.8.8.8/32, 2001:4860:4860::8888/128
- Only valid IP addresses are accepted (no hostnames).
Empty strings or whitespace-only values are not permitted.

IPv4 requirements

Octets: Each of the 4 octets must be a decimal number between 0–255.
Prefix length: Between /8 and /32.
Format: xxx.xxx.xxx.xxx/xx
- Valid examples:

1.1.0.0/16
8.8.8.0/24
8.8.8.8/32
203.0.113.0/24

IPv6 requirements

Segments: Valid hexadecimal digits (0–9, a–f; case-insensitive).
Prefix length: Between /48 and /128.
Format: Standard IPv6 notation with optional :: compression (only one :: per address).
- Valid examples:

2001:4860::/48
2001:db8::/64
2001:4860:4860::8888/128
2606:4700:4700::1111/128

Best practices

Keep a complete inventory of all outbound egress IPs used by the Partner's systems and automation.
Do not use dynamic IPs for outbound traffic that may change without notice.
Log and monitor:
- In reporting mode, capture Klarna-Ip-Validation-Status response header to identify gaps before enforcement.
- Post-enforcement, monitor blocked-traffic signals on the Partner's side.
- Plan change windows for enforcement updates to reduce risk of accidental lockouts.

Troubleshooting

Klarna-Ip-Validation-Status: DENIED
- The source IP is not on the allowlist. Add the IP/CIDR, validate in reporting mode, then re-enforce.
Klarna-Ip-Validation-Status: INVALID
- A technical error occurred during IP validation. Contact the standard Partner support channel.
Updates to the allowlist rejected while enforced
- Disable enforcement to remove or replace entries.
- Use the append-endpoint to extend the currently allowed IPs
No immediate effect after change.
- Allow up to 5 minutes for changes to propagate.

Frontend vs. backend responsibilities

This feature is backend-only. Configure and operate IP address restrictions in the backend deployment and network egress layer. No frontend changes are required.

Set up IP address restrictions

Setup IP address restrictions

Overview

How it works

Prerequisites

Endpoints

IP Allowlist management

IP restriction enforcement management

Implement IP address restrictions

1) Start in reporting mode

2) Set the IP allowlist

3) Validate in reporting mode

3) (Optional) Get the configured IP allowlist

4) Enforce the IP allowlist restriction

5) Disable enforcement

Maintenance of IP allowlist

Append the allow list

Manage IP addresses while enforcement is active

Using the PATCH endpoint

Endpoint

Overview

Enforcement modes

Request parameters

Understanding the enforcement_mode Parameter

Enforcement mode transitions

1. NOT_ENABLED → REPORTING

2. REPORTING → ENFORCED

3. ENFORCED → REPORTING

4. ENFORCED → NOT_ENABLED

5. REPORTING → NOT_ENABLED

6. NOT_ENABLED → ENFORCED

7. NOT_ENABLED → NOT_ENABLED

8. REPORTING → REPORTING

9. ENFORCED → ENFORCED

IP address restriction flow diagram

IP address format requirements

General requirements

IPv4 requirements

IPv6 requirements

Best practices

Troubleshooting

Frontend vs. backend responsibilities

Understanding the `enforcement_mode` Parameter