Client-side Tokens

Client-side tokens are an essential part of API security from SagaPay that allows client applications (like web browsers or mobile apps) to authenticate directly with the SagaPay API without using sensitive API-KEY or API-SECRET. This significantly enhances the security of your integrations.

With the client-side token, you can perform requests related to:

Orders
Payments
Transactions
Tips
Reporting
Branding
Receipts

Note

Client-side tokens are designed for customer-facing or operational tasks. You cannot use them to perform administrative tasks (e.g., creating merchants, managing stores, or other backend administrative functions). These tasks still require your full API credentials.

Prerequisites

API Credentials and merchantId to generate tokens.

Create Tokens

Tokens are generated by sending a POST request to the Client Auth Token API, with required parameters:

Parameter	Description
`providerId`	Your unique provider identifier that authenticates your system as the source requesting the token.
`providerCertificate`	The security certificate associated with your provider identity.
`externalUserId`	A unique string identifier for the specific user (e.g., a customer ID from your system) for whom the token is being created.

Note

To get providerId and providerCertificate, kindly contact support@sagapay.no.

This API returns a response of token and validUntil, the generated token must be included in future requests to SagaPay.

Every token has an expiration period, after which a new token must be fetched.

Using Client-side Tokens

To authorize your API requests using a client-side token, you must include the generated token in the authorization header of your API call.

The token should be passed as a Bearer Token, following this format:

Authorization: Bearer <YOUR_TOKEN>

Initiate a Payment with Client-side Tokens

$ curl -d '{
>           "orderId": "834572bb30e7903b0b",
>           "paymentMethod": "CARD"
>          }' \
>      -H 'Content-Type: application/json' \
>      -H 'Authorization: Bearer <YOUR_TOKEN>' \
>      YOUR_API_URL/payments

Replace <YOUR_TOKEN> with the actual token you received from the Client Auth Token API.

Token Lifecycle

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Request Token  │ --> │   Use Token     │ --> │  Token Expires  │
│  from API       │     │   in Headers    │     │  Refresh Token  │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Best Practices

Refresh Before Expiry

Implement token refresh logic before the token expires to ensure uninterrupted service.

Secure Storage

Store tokens securely and never expose them in URLs or logs.

One Token Per User

Generate unique tokens per user session using the externalUserId parameter.

Handle Expiry Gracefully

Implement proper error handling for expired tokens and automatically request new ones.

Comparison: API Credentials vs Client-side Tokens

Feature	API Credentials	Client-side Tokens
Use Case	Server-to-server	Client applications
Security	Must be kept secret	Safe for client-side
Expiration	Never expires	Time-limited
Scope	Full API access	Limited to operational tasks
Admin Tasks	✅ Allowed	❌ Not allowed