Authentication

OAuth Authentication Guide

Copy page

Overview

SaligPay uses OAuth 2.0 client credentials flow for API authentication. Merchants register to receive client credentials, then exchange them for JWT access tokens used in API requests.

Authentication Flow

Code
 
Your Server              SaligPay OAuth              SaligPay API
    │                        │                          │
    ├── POST /oauth ────────►│                          │
    │   authenticate         │                          │
    │◄── access_token ───────┤                          │
    │                        │                          │
    ├── GET /api/checkout ────────────────────────────►│
    │   Authorization: Bearer <token>                  │
    │◄── 200 OK ──────────────────────────────────────┤

Quick Start

Step 1: Register a Merchant (Admin Only)

Code
 
import { SaligPay } from "saligpay-node";

const saligpay = new SaligPay({
    adminKey: process.env.SALIGPAY_ADMIN_KEY!,
    env: "sandbox",
});

const result = await saligpay.auth.loginAndRetrieveCredentials(
    "merchant@example.com",
    "secure-password",
);

console.log("Client ID:", result.credentials.clientId);
console.log("Client Secret:", result.credentials.clientSecret);

Step 2: Authenticate

Code
 
const saligpay = new SaligPay({
    clientId: process.env.SALIGPAY_CLIENT_ID!,
    clientSecret: process.env.SALIGPAY_CLIENT_SECRET!,
    env: "sandbox",
});

const tokens = await saligpay.authenticate();
console.log("Access Token:", tokens.accessToken);
console.log("Expires At:", tokens.expiresAt);

Step 3: Make Authenticated Requests

Code
 
// The SDK handles token injection automatically
const checkout = await saligpay.checkout.create({
    externalId: "order-123",
    amount: 10000,
    description: "Payment",
    webhookUrl: "https://yourapp.com/webhooks/saligpay",
    returnUrl: "https://yourapp.com/success",
    contact: { name: "John", email: "john@example.com" },
});

API Reference

Authenticate (Client Credentials)

POST /api/oauth/authenticate

Code
 
{
    "clientId": "client_a3JkZm5vcGg=",
    "clientSecret": "base64encodedsecret"
}

Response

Code
 
{
    "success": true,
    "data": {
        "accessToken": "eyJ...",
        "refreshToken": "eyJ...",
        "expiresAt": "2025-05-03T12:00:00Z"
    }
}

Refresh Token

POST /api/oauth/jwt/refresh

Code
 
{
    "token": "eyJ...",
    "clientId": "client_xxx"
}

Validate Access Token

POST /api/oauth/jwt/validate/access

Code
 
{
    "accessToken": "eyJ..."
}

Validate Refresh Token

POST /api/oauth/jwt/validate/refresh

Code
 
{
    "refreshToken": "eyJ..."
}

SDK Reference

AuthResource

Method	Description
authenticate(clientId?, clientSecret?)	Get access tokens
refreshToken(refreshToken, clientId?)	Refresh access token
loginAndRetrieveCredentials(email, password, adminKey?)	Full login flow
validateToken(accessToken)	Validate JWT

Token Management

Code
 
// Check if still authenticated
if (saligpay.isAuthenticated()) {
    console.log("Token is valid");
}

// Auto-refresh if expired
await saligpay.ensureAuthenticated();

Error Handling

Error	Cause	Solution
Invalid credentials	Wrong client ID or secret	Verify credentials
Token expired	Access token expired	Call ensureAuthenticated()
Invalid refresh token	Refresh token expired	Re-authenticate

Best Practices

• Store credentials securely (environment variables, secret managers)
• Never expose credentials in client-side code
• Use ensureAuthenticated() before API calls for auto-refresh
• Implement token refresh logic for long-running processes

---

Related Guides:

• SDK Authentication - For SDK auth details