API Keys

API keys are used to authenticate requests to the Straumur API. Merchants create and manage their keys in the Merchant Portal; partners who integrate on behalf of several merchants create theirs in the Partner Portal.

Getting Test API Keys

To develop against Straumur's Test environment, request access by sending an email to developers@straumur.is.

Merchant Keys and Partner Keys

There are two kinds of API key. They are sent the same way and look the same — the difference is who issues them and what they can reach.

	Merchant key	Partner key
Issued in	Merchant Portal → API Keys	Partner Portal → API Keys
Belongs to	One merchant	One partner
Scoped by	The merchant's own agreements (contracts)	The partner's partner agreements
Can reach	Terminals under the selected agreements	Terminals of every merchant linked to the selected partner agreements
Typical use	A merchant integrating their own shop	A software house, platform or reseller processing payments for many merchants with one key

A partner key's reach is resolved on every request. When a new merchant is linked to one of the partner agreements the key covers (you receive a ContractLinked webhook), the key can process for that merchant immediately — no key change is needed.

Which merchant does a partner key act for?

The key itself does not name a merchant. Every request identifies the merchant through the terminalIdentifier you send — see How a request is authorised below.

Managing API Keys in the Merchant Portal

1. Log in to the Merchant Portal.
2. Navigate to API Keys in the menu.

Creating a New API Key

1. Click Generate new key.
2. Enter a descriptive name for the key (e.g., "Production Website" or "Mobile App").
3. Choose the key's scope: tick Subscribe to all agreements, or select one or more agreements. A key must cover at least one agreement.
4. Click Generate key.
5. Important: Copy and securely store the key. For security reasons, the full key is only available to copy for 24 hours after creation.

warning

Store your API keys securely. Never expose them in client-side code, public repositories, or logs.

Subscribe to all agreements

A key subscribed to all agreements also covers agreements added to your merchant account in the future. A key limited to specific agreements only ever covers those — if you sign a new agreement, edit the key or create a new one.

Viewing Existing Keys

The API Keys page displays all your existing keys with the following information:

• Key name: The descriptive name you assigned to the key.
• Api key: Last four letters of the API key. Copy button active if less than 24h from creation of the key.
• Agreements: The agreements the key covers, or All.
• Status: Whether the key is active or disabled.
• Date Created: When the key was created.

note

For security purposes, only a partial view of the key is shown, and after 24 hours the key cannot be copied. If you've lost a key, you'll need to create a new one.

Editing an API Key

Click Edit on a key to rename it or change which agreements it covers. The key value itself never changes — to rotate a key, create a new one and disable the old one.

Disabling an API Key

If an API key is compromised or no longer needed, you should disable it:

1. Find the key in the API Keys list.
2. Click the Disable button.
3. Confirm the action.

danger

Disabling a key is immediate and permanent. Any applications using that key will immediately lose access to the API.

Managing API Keys in the Partner Portal

Partner keys work the same way, but are scoped by partner agreements rather than merchant agreements.

1. Log in to the Partner Portal.
2. Navigate to API Keys in the menu.
3. Click Generate new key.
4. Enter a Key name.
5. Choose the key's scope: tick Subscribe to all agreements, or select one or more Partner agreements. A key must cover at least one.
6. Click Generate, then copy the key. As with merchant keys, the full key can only be copied for 24 hours after creation.

The list shows each key's name, masked value, status, the Partner Agreements it covers (or All), who created or disabled it, and when. Edit lets you rename a key or change its agreements; Disable is immediate and permanent.

Subscribe to all agreements

For a partner key this means every partner agreement you have today and any added in the future. Because reach is resolved per request, a key subscribed to all agreements can process for every merchant that is, or later becomes, linked to your partnership — with no further key management.

Contracts and Terminals

Each API key is linked to one or more contracts. A contract determines which e-commerce solutions (terminals) the key can access:

Solution	Description
Hosted Checkout	Straumur-hosted payment page integration
Payment Gateway	Direct API integration for custom checkout
Payment Links	Create and share payment links
Tokenize Links	Create links for card tokenization
Shopify	Shopify store integration
WooCommerce	WooCommerce store integration

info

The available solutions depend on your contract configuration. To enable additional solutions, contact Straumur.

Using Your API Key

Include your API key in the header of all API requests:

• X-API-Key: your-api-key-here

Example:

curl -X GET "https://checkout-api.staging.straumur.is/api/v1/hostedcheckout/status/faf984ad76db7b2dea3f7bab" \
  -H "X-API-Key: e684c4be6b2b2318c0433b185b7e34ac2bfe941fcf4370ca9d"

How a request is authorised

Every request goes through the same two checks, whether the key is a merchant key or a partner key:

1. Is the key valid? The key must exist and be active. A missing, unknown or disabled key is rejected with HTTP 401.
2. May this key use this terminal? The terminalIdentifier in the request is looked up. Its contract must be active, the merchant must be active, and the contract must be within the key's reach — the merchant's selected agreements for a merchant key, or the merchants linked to the selected partner agreements for a partner key. If any of these fail, the request is rejected with error 2016 — Merchant cannot access terminal or terminal does not exist.

Symptom	Meaning
401 Unauthorized	The key itself is wrong: mistyped, disabled, or not sent in X-API-Key.
Error 2016	The key is fine, but the terminal is not one it may use. Check that the terminalIdentifier belongs to a merchant and agreement the key covers, and that both are active.

A partner key therefore needs nothing merchant-specific in the request beyond the terminal identifier. Use the same key for all of your merchants and switch between them by sending each merchant's own terminalIdentifier.