Sign in →Book a demo

Developers Guides Client Auth Tokens

Client Auth Tokens

Generate client-side authentication tokens for secure API access from browsers and mobile apps without exposing your API key or secret.

Online API Authentication Security

Overview

Client auth tokens let client-side applications (web browsers, mobile apps) authenticate with the Surfboard API without exposing your API-KEY or API-SECRET. Use them for customer-facing operations where you need to call the API directly from the frontend.

What You Can Do With Client Tokens

Client tokens support operational API requests:

Orders
Payments
Transactions
Tips
Reporting
Branding
Receipts

Note: Client tokens cannot perform administrative tasks like creating merchants, managing stores, or other backend operations. Those still require full API credentials.

Create a Token

Generate a token by sending a POST request with your auth provider credentials.

POST /partners/:partnerId/token

Request

{
  "providerId": "YOUR_PROVIDER_ID",
  "providerCertificate": "YOUR_PROVIDER_CERTIFICATE",
  "externalUserId": "user_12345"
}

Parameter	Type	Required	Description
`providerId`	string	Yes	Provider ID of the auth provider
`providerCertificate`	string	Yes	Certificate of the auth provider
`externalUserId`	string	Yes	Unique identifier for the user (e.g., a customer ID from your system)
`email`	string	No	Email address of the user

Note: To get your providerId and providerCertificate, contact integrations@surfboard.se or reach out via Slack.

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "validUntil": "3600",
  "status": "SUCCESS",
  "message": "Token created successfully"
}

The validUntil field indicates the token’s validity period in seconds. When a token expires, generate a new one.

Using Client Tokens

Include the token in the Authorization header as a Bearer token:

Authorization: Bearer <YOUR_TOKEN>

Example: Initiate a Payment

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

Token Lifecycle

Generate a token from your backend using full API credentials
Pass the token to your frontend application
Use the token for client-side API calls
Refresh the token when it expires by generating a new one from your backend

Keep your API-KEY and API-SECRET on the server side. Only the generated token should reach the client.

Other Guides

Tap to Pay on iPhone SDK

Accept contactless payments directly on iPhone. Complete integration guide for Surfboard's iOS SoftPOS SDK -- from setup to production.

Android SoftPOS SDK

Turn Android devices into payment terminals with the Surfboard Android SoftPOS SDK. Complete integration guide from setup to production.

EMV Terminal Integration

Integrate traditional card-present terminals through Surfboard's unified API. From account setup to live payments in one guide.

Payment Page

Redirect customers to a Surfboard-hosted checkout page. The fastest way to accept online payments with minimal integration effort.

Inter-App Integration

Integrate your POS app with CheckoutX using native app switch. Register terminals, process payments, and scan NFC tags through a bi-directional deep link flow.

Self-Hosted Checkout

Embed a payment form directly in your web app with the Surfboard Online SDK. Full UI control with Surfboard handling PCI compliance.

Server-to-Server API

Process online payments entirely from your backend with Merchant Initiated Transactions. Full control over recurring payments, subscriptions, and tokenized card flows.

Create an Order

Learn how to create orders with line items, tax, customer details, and control functions. The starting point for accepting payments with the Surfboard API.

Merchant Onboarding

Set up merchants and stores on the Surfboard platform. Walk through the full onboarding flow from merchant creation to KYB completion and store setup.

Payment Lifecycle

Manage the full payment lifecycle from order creation through capture, void, cancel, and refund operations using the Surfboard Payments API.

Capture a Payment

Finalize a previously authorized payment by capturing funds. Covers delay capture and pre-authorization flows with step-by-step API examples.

Terminal & Device Management

Manage payment terminals and devices via the Surfboard API. Register in-store and online terminals, configure settings, and handle device operations.

Cancel a Payment

Stop an in-progress payment before it completes. Use cancellation when a customer abandons checkout or a payment needs to be halted mid-process.

Webhooks & Notifications

Receive real-time event notifications via webhooks, email, Slack, and SFTP. Subscribe to payment events and settlement reports for merchants and partners.

Recurring Payments

Implement subscription billing and recurring charges using tokenization, recurring payment configuration, and Merchant Initiated Transactions.

Void a Payment

Reverse a completed payment before settlement. Voiding stops funds from transferring to the merchant's account, avoiding incorrect transactions.

Receipts

Generate, email, print, and customise receipts for in-store transactions using the Surfboard Receipts API.

Refund an Order

Process a full refund by creating a return order with negative quantities. Covers the complete refund flow with API examples and payment method requirements.

Partial Refund

Refund specific items or a reduced amount from a completed order. Process partial returns by creating a return order with only the items to be refunded.

Tips Configuration

Configure tipping on Surfboard payment terminals at the merchant, store, or terminal level using a hierarchical override model.

NFC Tag Reading

Use the NFC Reading API to create tag-reading sessions on payment terminals, scan NFC/RFID-tagged products, and retrieve scanned tag data.

Partial Payments

Split an order across multiple payment methods or transactions. Accept card, cash, and Swish in any combination to settle a single order.

Multi-Merchant Terminals

Set up shared payment terminals for multiple merchants using the Multi-Merchant Group API. Ideal for food courts, events, and co-located businesses.

Store Management

Create, update, verify, and manage in-store and online stores using the Surfboard Payments Store APIs.

Gift Cards & Promotions

Issue and manage gift cards, track transactions, and create marketing promotions using the Surfboard Payments APIs.

Product Catalog

Create and manage product catalogs, products, variants, inventory levels, and analytics through the Catalog API.

Settlements & Reporting

Retrieve settlement reports, view adjustments, manage merchant charges, and register customer profiles for reconciliation and billing.

Account & Service Provider Management

Create merchant and partner accounts, manage user roles, register service providers, and configure external notifications via the Surfboard API.

Payment Methods

Activate, deactivate, and list payment methods for a merchant. Manage card, Swish, Klarna, AMEX, Vipps, MobilePay, and more via the API or Partner Portal.

Partner Branding

Configure white-label branding for terminals and payment pages. Set colors, fonts, logos, and cover images at the partner level via API or Partner Portal.

Ready to get started?

Create a sandbox account and start building your integration today.

Create Sandbox Account All Guides