Manage allowed client origins for the Klarna Web SDK

Configure the per-account allowlist of web origins that are authorized to load the Klarna Web SDK, using the account-scoped and Partner Account-scoped endpoints of the Partner management API.

38 min read

The Allowed Client Origins API lets you control which web origins can load the Klarna Web SDK on behalf of your account or one of your child Partner Accounts. Each origin you add becomes part of an allowlist that Klarna evaluates whenever a browser asks the Web SDK to render Klarna in your checkout.

Use this guide to list, add, read, and remove allowed origins, recover from a BLOCKED origin, and safely reconcile 409 RESOURCE_CONFLICT responses when you retry a create call.

Key takeaways

The Allowed Client Origins API exposes a CRUD surface (list, create, read, delete) for the per-account allowlist of web origins authorized to load the Klarna Web SDK, with matching variants for your own account and for any child Partner Account you manage.
You submit an origin as host plus optional port without a scheme. Klarna resolves the scheme (localhost becomes http://, everything else becomes https://) and returns the resolved value together with a KRN identifier.
Wildcard subdomains such as *.example.com are always supported. The bare wildcard * is supported only in non-production environments.
Each account can hold up to 100 origins, returned alphabetically in a single page. Pagination parameters are accepted for forward compatibility.
Use Klarna-Idempotency-Key (UUID v4 or higher) on create requests to make retries safe. Without the header, a 409 RESOURCE_CONFLICT is safe to treat as success. With the header, a 422 IDEMPOTENCY_KEY_MISMATCH indicates a client-side bug and must not be treated as success.
Each allowed origin has a state of either ALLOWED or BLOCKED. To attempt remediation of a BLOCKED origin, delete it and re-create it.

Coming soon

The Allowed Client Origins API is in early-release and is not generally available in the test environment or production. Access is gated per account. Coordinate with your Klarna integration contact before you begin building, so the feature can be enabled for the accounts you want to manage.

Before you start

Make sure the following is in place before you call any of the endpoints described in this guide:

You have valid Acquiring Partner credentials for the Partner management API.
Your access token grants the right OAuth scopes for the calls you plan to make:
- account-credentials:read for listAllowedOrigins, readAllowedOrigin, listAllowedOriginsForPartnerAccount, and readAllowedOriginForPartnerAccount.
- account-credentials:write for createAllowedOrigin, deleteAllowedOrigin, createAllowedOriginForPartnerAccount, and deleteAllowedOriginForPartnerAccount.
Klarna has enabled the Allowed Client Origins feature for your account (and for any child Partner Accounts you intend to manage).
You've decided which scope each call should use:
- Use the /account/integration/inbound-restrictions/origins endpoints to manage origins for your own account.
- Use the /accounts/{partner_account_id}/integration/inbound-restrictions/origins endpoints to manage origins for a child Partner Account you manage.
You can generate UUID v4 (or higher) values to use as Klarna-Idempotency-Key headers on create calls.

How origins are validated and resolved

Klarna validates and stores allowed origins using a small, well-defined input format. Understanding the format up front prevents most 400 BAD_REQUEST errors at create time.

Input format. Submit an origin as host with an optional port — never include a scheme:

Hostname: lowercase ASCII letters, digits, and hyphens; each DNS label is at most 63 characters.
Port: optional, between 1 and 65535. When present, append it as :<port>.
Internationalized domain names: submit them in punycode form (for example, xn--mnchen-3ya.example.com).
localhost is supported.

Scheme resolution. Klarna assigns the scheme for you and returns the resolved value in the response:

localhost and localhost:<port> resolve to http://.
Every other host resolves to https://.
The bare wildcard * resolves to https://* and is accepted only in non-production environments.

Wildcards. Wildcard subdomains in the form *.example.com are supported in all environments. They match any single subdomain segment under the parent zone. Use them sparingly — every additional wildcard widens the surface area that can load the Klarna Web SDK on your behalf.

Do	Don't
`shop.example.com`	`https://shop.example.com` — don't include the scheme; Klarna resolves it.
`checkout.example.com:8443`	`shop.example.com/checkout` — paths aren't part of an origin.
`*.example.com`	`` or `..example.com` — the bare wildcard is allowed only in non-production, and only single-segment wildcards like `.example.com` are supported.
`localhost` or `localhost:3000`	`Shop.Example.com` — submit hostnames in lowercase.
`xn--mnchen-3ya.example.com`	`shop.example.com:0` or `shop.example.com:70000` — port must be `1`–`65535`.

How a typical add-origin call flows

The sequence below shows the recommended add-origin flow, including the safe retry path when the network drops your first request.

sequenceDiagram participant AP as Acquiring Partner backend participant K as Klarna Partner management API AP->>AP: Generate Klarna-Idempotency-Key (UUID v4+) AP->>K: POST /account/integration/inbound-restrictions/origins { "origin": "shop.example.com" } Klarna-Idempotency-Key: <uuid> alt First attempt succeeds K-->>AP: 201 Created Location: /…/origins/{origin_id} { origin_id, origin, state: ALLOWED, … } AP->>AP: Persist origin_id else Network error or timeout AP->>K: Retry POST with the SAME body and SAME Klarna-Idempotency-Key K-->>AP: 201 Created (same resource as the original call) AP->>AP: Persist origin_id else Idempotency key reused with a different body K-->>AP: 422 IDEMPOTENCY_KEY_MISMATCH AP->>AP: Fix client bug (do NOT treat as success) end

List allowed origins

Read the current allowlist for an account when you need to audit which origins are configured, populate an internal admin UI, or confirm a recent change took effect.

For your own account, call listAllowedOrigins.
For a child Partner Account, call listAllowedOriginsForPartnerAccount with the partner_account_id path parameter.

Origins are returned alphabetically in a single page (up to 100 per account). The size, starting_after, and ending_before query parameters are accepted for forward compatibility, but you don't need to paginate to read the full list today.

BASH

1 2 3

curl -X GET \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.klarna.com/account/integration/inbound-restrictions/origins

Example 200 OK response:

JSON

1 2 3 4 5 6 7 8 9 10

{
  "origins": [
    {
      "origin_id": "krn:network:global:live:account:allowed-origin:f7e8d9c0-b1a2-3456-cdef-7890abcdef12",
      "origin": "http://localhost:3000",
      "state": "ALLOWED",
      "created_at": "2026-03-01T08:00:00.000Z",
      "updated_at": "2026-03-01T08:00:00.000Z"
    },
    {

Add a new allowed origin

Add an origin whenever a new storefront, staging environment, or wildcard subdomain needs to load the Klarna Web SDK.

For your own account, call createAllowedOrigin.
For a child Partner Account, call createAllowedOriginForPartnerAccount.

The request body contains a single origin field. Always set the Klarna-Idempotency-Key header so retries are safe. The header value must be a UUID v4 (or higher) and may be 1–255 characters long.

BASH

1 2 3 4 5 6

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Klarna-Idempotency-Key: 4f3a8b2e-7d51-4a3c-9c2e-1a2b3c4d5e6f" \
  https://api.klarna.com/account/integration/inbound-restrictions/origins \
  -d '{"origin": "new-shop.example.com"}'

Example 201 Created response:

JSON

1 2 3 4 5 6 7

{
  "origin_id": "krn:network:global:live:account:allowed-origin:206bbb83-9b6e-46fa-940d-337153c04a58",
  "origin": "https://new-shop.example.com",
  "state": "ALLOWED",
  "created_at": "2026-04-14T10:30:00.000Z",
  "updated_at": "2026-04-14T10:30:00.000Z"
}

The response also includes a Location header pointing at the new resource. Persist the returned origin_id (the KRN) in your own systems so you can later read or delete the origin without listing first.

Reconcile a 409 RESOURCE_CONFLICT

If you retry a create call without the Klarna-Idempotency-Key header (or with a different key) and the origin already exists, Klarna returns 409 RESOURCE_CONFLICT:

JSON

1 2 3 4 5 6

{
  "error_id": "7c123a8e-321b-4a2b-9fc4-2a7e89b5c0c5",
  "error_type": "RESOURCE_ERROR",
  "error_code": "RESOURCE_CONFLICT",
  "error_message": "The origin https://shop.example.com is already configured for this account."
}

This is safe to treat as a successful terminal outcome — the origin you wanted to add is already on the allowlist. To recover the resource identifiers, list the origins and look up the matching origin_id.

Always send idempotency key

The cleanest pattern is to always send Klarna-Idempotency-Key on create calls. With the header in place, a retry of the same request returns the original 201 Created response (including the original origin_id), so you don't need a follow-up list call to reconcile.

Don't treat 422 IDEMPOTENCY_KEY_MISMATCH as success

If you reuse a Klarna-Idempotency-Key value with a different request body, Klarna returns 422 IDEMPOTENCY_KEY_MISMATCH:

JSON

1 2 3 4 5 6

{
  "error_id": "9bcf5d12-8ef7-46a9-b2cb-d24a9b9db3c2",
  "error_type": "INPUT_ERROR",
  "error_code": "IDEMPOTENCY_KEY_MISMATCH",
  "error_message": "The Klarna-Idempotency-Key has already been used with a different request body."
}

Integration requirement

A 422 IDEMPOTENCY_KEY_MISMATCH response means your client reused an idempotency key for a semantically different request. This is a client-side bug — the origin you tried to add was not stored, and you must not treat the response as success. Generate a fresh UUID v4 for each new logical request and retry.

Read a specific allowed origin

Look up a single origin when you already have its origin_id (the KRN) and want to confirm its current state or audit metadata such as created_at and updated_at.

For your own account, call readAllowedOrigin.
For a child Partner Account, call readAllowedOriginForPartnerAccount.

BASH

1 2 3

curl -X GET \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.klarna.com/account/integration/inbound-restrictions/origins/$ORIGIN_ID

Example 200 OK response:

JSON

1 2 3 4 5 6 7

{
  "origin_id": "krn:network:global:live:account:allowed-origin:206bbb83-9b6e-46fa-940d-337153c04a58",
  "origin": "https://shop.example.com",
  "state": "ALLOWED",
  "created_at": "2026-04-01T09:45:00.000Z",
  "updated_at": "2026-04-01T09:45:00.000Z"
}

Remove an allowed origin

Delete an origin when it's no longer needed (for example, you're decommissioning a storefront) or as the first step in remediating a BLOCKED origin.

For your own account, call deleteAllowedOrigin.
For a child Partner Account, call deleteAllowedOriginForPartnerAccount.

BASH

1 2 3

curl -X DELETE \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.klarna.com/account/integration/inbound-restrictions/origins/$ORIGIN_ID

A successful delete returns 204 No Content. After the call, the Klarna Web SDK will stop loading from that origin. There's no soft-delete and no recovery — to bring the origin back, create it again.

Recover from a BLOCKED origin

Each allowed origin carries a state field with one of two values:

State	Meaning
`ALLOWED`	Klarna accepts requests from this origin to load the Klarna Web SDK.
`BLOCKED`	The origin is on the allowlist, but Klarna isn't currently permitting it (typically suspended for a policy violation or pending verification). Requests from this origin are turned away.

flowchart LR create((Create origin)) -->|201 Created| AL[ALLOWED] AL -->|Policy violation or pending verification| BL[BLOCKED] BL -->|DELETE origin| RM((Removed)) RM -->|Re-create with fresh Klarna-Idempotency-Key| CHK{State after re-create?} CHK -->|ALLOWED| AL CHK -->|BLOCKED| SUP((Contact Partner support))

Klarna doesn't expose a PATCH endpoint to change state. If one of your origins is BLOCKED and you believe the underlying issue has been resolved, follow this remediation pattern:

1.
Read the origin with readAllowedOrigin (or readAllowedOriginForPartnerAccount) and confirm state is BLOCKED.
2.
Delete the origin with deleteAllowedOrigin (or deleteAllowedOriginForPartnerAccount).
3.
Re-create the origin with createAllowedOrigin (or createAllowedOriginForPartnerAccount), using a fresh Klarna-Idempotency-Key. Klarna re-evaluates the origin and, if the underlying issue is resolved, returns it in state: ALLOWED.

If the re-created origin returns again as BLOCKED, contact your standard Partner support channel — the underlying suspension hasn't been cleared and another delete-and-create cycle won't help.

Best practices

Apply these practices to your allowlist configuration:

Do	Don't
Generate a fresh `Klarna-Idempotency-Key` (UUID v4 or higher) per logical create request, reuse it across retries, and treat the resulting `409 RESOURCE_CONFLICT` as a successful terminal outcome.	Reuse a `Klarna-Idempotency-Key` across semantically different requests, or treat the resulting `422 IDEMPOTENCY_KEY_MISMATCH` as success — the origin was not stored.
Persist the returned `origin_id` (KRN) in your own systems so reads and deletes don't require a list call first.	Hard-code `origin_id` values across environments — they're issued per account, per environment.
Submit hostnames in lowercase ASCII (use punycode for internationalized domains).	Submit origins with a scheme (`https://...`) or a path (`shop.example.com/checkout`).
Keep wildcards narrow — prefer `shop.example.com` over `*.example.com` whenever the set of subdomains is stable.	Use the bare wildcard `*` outside of non-production environments.
Audit your allowlist regularly and remove origins for storefronts you no longer operate.	Assume a `BLOCKED` origin will recover on its own; you must delete and re-create to retry.

Reference

Endpoints

The Allowed Client Origins API exposes the same four CRUD actions in two scopes — one for your own account, and one for any child Partner Account you manage.

Action	OperationId	Method	Path	Required scope
List origins (own)	listAllowedOrigins	`GET`	`/account/integration/inbound-restrictions/origins`	`account-credentials:read`
Add origin (own)	createAllowedOrigin	`POST`	`/account/integration/inbound-restrictions/origins`	`account-credentials:write`
Read origin (own)	readAllowedOrigin	`GET`	`/account/integration/inbound-restrictions/origins/{origin_id}`	`account-credentials:read`
Delete origin (own)	deleteAllowedOrigin	`DELETE`	`/account/integration/inbound-restrictions/origins/{origin_id}`	`account-credentials:write`
List origins (child)	listAllowedOriginsForPartnerAccount	`GET`	`/accounts/{partner_account_id}/integration/inbound-restrictions/origins`	`account-credentials:read`
Add origin (child)	createAllowedOriginForPartnerAccount	`POST`	`/accounts/{partner_account_id}/integration/inbound-restrictions/origins`	`account-credentials:write`
Read origin (child)	readAllowedOriginForPartnerAccount	`GET`	`/accounts/{partner_account_id}/integration/inbound-restrictions/origins/{origin_id}`	`account-credentials:read`
Delete origin (child)	deleteAllowedOriginForPartnerAccount	`DELETE`	`/accounts/{partner_account_id}/integration/inbound-restrictions/origins/{origin_id}`	`account-credentials:write`

AllowedOrigin resource fields

Field	Type	Description
`origin_id`	string	KRN identifier for the resource (for example, `krn:network:global:live:account:allowed-origin:206bbb83-9b6e-46fa-940d-337153c04a58`). The `live` segment is `live` in production and `test` elsewhere.
`origin`	string	Resolved origin value, including the scheme Klarna assigned (`http://` for `localhost`, `https://` for everything else).
`state`	string	One of `ALLOWED` or `BLOCKED`. See Recover from a BLOCKED origin.
`created_at`	string	ISO 8601 timestamp (UTC) when the origin was added.
`updated_at`	string	ISO 8601 timestamp (UTC) when the origin was last modified by Klarna (for example, on a state change).

Error codes

HTTP status	Error code	When you'll see it	Recommended action
`400`	`BAD_REQUEST`	The `origin` value violates the input format (scheme included, invalid host, port out of range, bare `*` in production, etc.).	Fix the payload and retry. Don't reuse the previous `Klarna-Idempotency-Key`.
`401`	`UNAUTHORIZED`	The access token is missing, expired, or doesn't carry the required scope.	Refresh the token. Confirm `account-credentials:read` for read calls and `account-credentials:write` for create and delete calls.
`404`	`RESOURCE_NOT_FOUND`	The `origin_id` doesn't exist for this account, or the `partner_account_id` isn't a child of your Acquiring Partner account.	List the origins for the right scope and reconcile your local state.
`409`	`RESOURCE_CONFLICT`	An equivalent origin already exists on the allowlist and the request didn't carry a matching `Klarna-Idempotency-Key`.	Safe to treat as a successful terminal outcome — the origin is on the allowlist. Use a list call to recover the `origin_id`.
`422`	`IDEMPOTENCY_KEY_MISMATCH`	The `Klarna-Idempotency-Key` value was previously used with a different request body.	Don't treat as success. Fix the client bug, generate a new `Klarna-Idempotency-Key`, and retry the intended request.
`500`	`INTERNAL_SERVER_ERROR`	A transient server-side error.	Retry with exponential backoff, reusing the same `Klarna-Idempotency-Key` for create calls.

IP address restrictions — sibling inbound-restriction that limits which source IPs can call the Partner management API. Manage enforcement with readIpRestrictionEnforcementStatus and manageIpRestrictionEnforcement.
Configure mTLS — sibling credential-hardening feature that requires client certificates on inbound API traffic. Manage enforcement with readMTLSAuthorizationEnforcementStatus, enforceMTLSAuthorization, and removeEnforcementOfMTLSAuthorization.
Payment presentation overview — describes how the Klarna Web SDK presents Klarna in your checkout. The allowlist you manage with this API gates which web origins can load that SDK.

Setup IP Address Restrictions

Configure mTLS

Payment Presentation Overview

Jump to section...

Manage allowed client origins for the Klarna Web SDK

Before you start

How origins are validated and resolved

How a typical add-origin call flows

List allowed origins

Add a new allowed origin

Reconcile a 409 RESOURCE_CONFLICT

Don't treat 422 IDEMPOTENCY_KEY_MISMATCH as success

Read a specific allowed origin

Remove an allowed origin

Recover from a BLOCKED origin

Best practices

Reference

Endpoints

AllowedOrigin resource fields

Error codes

Related features