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.

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

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

• 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 your 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.

• You 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 isn’t on the allowlist.
  • INVALID: A technical error occurred during IP validation. Contact your standard Partner support channel.
• After you confirm the allowlist is correct, enable enforcement so requests from IP's not on the allowlist are blocked.

• API credentials authorized to manage account integration settings.
• A complete and accurate list of your 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.

• 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.

• 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.

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.

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.

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

You can observe the header on any API call while in reporting mode. For example:

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
...

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

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"]'

• Exercise your integration from each expected source IP.
• Inspect the response header to verify status:
  • ALLOWED indicates the source IP is on your allowlist.
  • DENIED indicates the source IP isn’t on your allowlist.
  • INVALID indicates a technical error; contact your standard Partner support channel.

Example response headers (truncated):

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

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

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

When you’ve confirmed the status from all expected traffic shows ALLOWED, enable enforcement.

Requirements:

• Your 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):

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):

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:

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 IP's that aren’t on your allowlist are blocked.
• Klarna-Ip-Validation-Status header is no longer included in responses.

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

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

You 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 IP's the you wish 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

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

When enforcement is enabled:

• You can add new CIDRs to the configured list (via the POST endpoint).
• You cannot replace CIDRs from the configured list.
• You cannot modify CIDRs from the configured list.
• If you need to remove or replace CIDR-blocks:
  • Switch to reporting mode (use the PATCH endpoint and change the enforcement_mode to REPORTING) .
  • Update the allowlist (PUT overwrite or POST append)
  • Validate in reporting mode until all expected sources show ALLOWED.
  • Re-enable enforcement.

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

The IP endpoint manages the enforcement state of your IP allowlist restrictions through a state machine with three modes: NOT_ENABLED, REPORTING, and ENFORCED. This endpoint allows you to transition 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 your allowlist configuration before enforcement.

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

Understanding the enforcement_mode Parameter

Critical Concept: The enforcement_mode in your request body represents your intention — what enforcement state you want 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 will match your requested mode.
• enforcement_type: SCHEDULED: Transitions at the specified future time. The response enforcement_mode will be REPORTING (transition pending) until the enforced_from timestamp is reached, at which point it becomes ENFORCED.

Example

// 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",
  "enforced_from": "2099-01-01T00:00:00Z"
}

This design provides a grace period where you can monitor the response status header Klarna-Ip-Validation-Status before enforcement activates, ensuring your allowlist is configured correctly.

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 your configured CIDR block/s.

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

Example

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

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

2. REPORTING → ENFORCED

Behavior: Upgrades from monitoring to blocking. RECOMMENDED PATH for production after validating your 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:

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

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

Scheduled enforcement:

// 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",
  "enforced_from": "2026-02-01T00:00:00Z"
}

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:

// 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:

// 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:

// 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:

// 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: You cannot schedule future enforcement while staying in REPORTING mode. To schedule enforcement, you must transition to ENFORCED mode (see transition #6).

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

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

Invalid Request:

// ❌ 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, don't 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

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

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

When configuring the allowlist, all entries must meet these 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 aren’t permitted.

• 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

• 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

• Keep a complete inventory of all outbound egress IPs used by your systems and automation.
• Do not use dynamic IPs for your 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 your side.
  • Plan change windows for enforcement updates to reduce risk of accidental lockouts.

• Klarna-Ip-Validation-Status: DENIED
  • The source IP isn’t 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 your 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.

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