Authentication

All SagaPay API requests require authentication using your API credentials. This page explains how to obtain and use your credentials securely.

API Credentials

Each API request must include the following headers:

Header	Description	Required
`X-API-Key`	Your unique API key	✅ Yes
`X-API-Secret`	Your API secret (keep this safe!)	✅ Yes
`X-Merchant-ID`	Your merchant identifier	✅ Yes
`X-Store-ID`	Store identifier (if store-scoped)	⚪ Optional

Example Request

$ curl -X GET https://api.sagapay.no/v1/terminals \
>   -H "X-API-Key: spk_live_abc123def456" \
>   -H "X-API-Secret: sps_live_xyz789uvw012" \
>   -H "X-Merchant-ID: merch_abc123"

Obtaining Credentials

1. Access the Key Management Portal

Visit the Key Management section in this documentation to create and manage your API keys.

2. Verify Your Identity

You’ll need to verify ownership of your merchant account:

Enter your Merchant ID and Store ID
We’ll send a one-time code to the email registered with that store
Enter the code to access key management

3. Create an API Key

Once verified, you can:

Create new API keys with custom names
Set permissions for each key
Optionally scope keys to specific stores
Set expiration dates

Important: Your API Secret is only shown once when created. Save it immediately in a secure location. If you lose it, you’ll need to create a new key.

API Key Scoping

API keys can be scoped to limit their access:

Merchant-Level Keys

Access all stores under your merchant account:

Merchant ID: merch_abc123
Store ID: (not set)
→ Can access: All stores under merch_abc123

Store-Level Keys

Access only a specific store:

Merchant ID: merch_abc123  
Store ID: store_xyz789
→ Can access: Only store_xyz789

Best Practice: Use store-scoped keys whenever possible. This limits the blast radius if a key is compromised.

Security Best Practices

Never expose your API Secret

Don’t commit secrets to version control
Don’t include secrets in client-side code
Use environment variables or secret managers

Use store-scoped keys

Create separate keys for each store
Limit permissions to what’s needed
Rotate keys periodically

Monitor API usage

Check the Key Management portal for usage stats
Set up alerts for unusual activity
Revoke unused keys

Use HTTPS only

All API requests must use HTTPS
HTTP requests will be rejected

Rate Limits

To protect the API, we enforce rate limits:

Endpoint Category	Limit
Orders	60 requests/minute
Payments	60 requests/minute
Terminals	200 requests/minute
Other	100 requests/minute

Rate limit headers are included in all responses:

1 X-RateLimit-Limit: 60
2 X-RateLimit-Remaining: 45
3 X-RateLimit-Reset: 2026-01-24T10:31:00Z

If you exceed the limit, you’ll receive a 429 Too Many Requests response:

1 {
2   "code": "RATE_LIMITED",
3   "message": "Too many requests. Please slow down.",
4   "retryAfter": 30
5 }

Error Responses

401 Unauthorized

Missing or invalid credentials:

1 {
2   "code": "UNAUTHORIZED",
3   "message": "Invalid API key or key has been revoked."
4 }

403 Forbidden

Key doesn’t have access to the requested resource:

1 {
2   "code": "FORBIDDEN",
3   "message": "API key is not authorized for this merchant."
4 }

Revoking Keys

If you believe a key has been compromised:

Go to Key Management
Verify your identity with OTP
Find the compromised key
Click “Revoke” to immediately disable it

Revoked keys cannot be reactivated. You’ll need to create a new key.