Authentication

Overview

The SDK uses JWT token-based authentication to keep your API credentials secure. Instead of exposing your Client ID and Secret in browser code, tokens are generated server-side by your backend.

---

Why Token-Based Authentication?

Security Benefits:

• API credentials (Client ID/Secret) never leave your server

• Tokens are scoped to specific customers and invoices

• Tokens have limited lifetime, reducing exposure risk

• Token refresh is handled automatically by the SDK

---

Authentication Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Your           │     │  Your           │     │  Alternative    │
│  Backend        │     │  Frontend       │     │  API            │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │  1. POST /v1/checkout-auth/init              │
         │  (with OAuth2 client credentials)            │
         │──────────────────────────────────────────────>│
         │                       │                       │
         │  2. Returns JWT token                        │
         │<──────────────────────────────────────────────│
         │                       │                       │
         │  3. Pass token to frontend                   │
         │──────────────────────>│                       │
         │                       │                       │
         │                       │  4. SDK uses token    │
         │                       │  for all API calls    │
         │                       │──────────────────────>│
         │                       │                       │
         │                       │  5. Token expires     │
         │                       │  onAccessTokenExpired │
         │                       │  callback triggered   │
         │                       │<─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│
         │                       │                       │
         │  6. Frontend requests │                       │
         │  new token            │                       │
         │<──────────────────────│                       │
         │                       │                       │
         │  7. New token returned│                       │
         │──────────────────────>│                       │
         │                       │                       │
         │                       │  8. SDK continues     │
         │                       │  with new token       │
         │                       │──────────────────────>│

---

Backend Implementation

Step 1: Get OAuth Token

First, exchange your Client ID and Secret for an OAuth access token:

curl -X POST https://public-api.alternativepayments.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
  -d "grant_type=client_credentials"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

Step 2: Generate Checkout Token

Use the OAuth token to generate a checkout token for a specific customer and invoice:

curl -X POST https://public-api.alternativepayments.io/v1/checkout-auth/init \
  -H "Authorization: Bearer {oauth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xxx",
    "invoice_id": "inv_xxx"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1703980800
}

Complete Backend Example

Node.js (Express)

import express from 'express';

const router = express.Router();

const CLIENT_ID = process.env.ALTERNATIVE_CLIENT_ID;
const CLIENT_SECRET = process.env.ALTERNATIVE_CLIENT_SECRET;
const API_BASE = 'https://public-api.alternativepayments.io';

// Cache OAuth token
let oauthToken: { token: string; expiresAt: number } | null = null;

async function getOAuthToken(): Promise<string> {
  // Return cached token if valid
  if (oauthToken && oauthToken.expiresAt > Date.now() + 60000) {
    return oauthToken.token;
  }

  const response = await fetch(`${API_BASE}/oauth/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')}`,
    },
    body: 'grant_type=client_credentials',
  });

  const data = await response.json();
  oauthToken = {
    token: data.access_token,
    expiresAt: Date.now() + data.expires_in * 1000,
  };

  return data.access_token;
}

router.post('/api/checkout-token', async (req, res) => {
  try {
    const { customerId, invoiceId } = req.body;

    // Validate inputs
    if (!customerId || !invoiceId) {
      return res.status(400).json({ error: 'customerId and invoiceId are required' });
    }

    // Get OAuth token
    const accessToken = await getOAuthToken();

    // Generate checkout token
    const response = await fetch(`${API_BASE}/v1/checkout-auth/init`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        customer_id: customerId,
        invoice_id: invoiceId,
      }),
    });

    if (!response.ok) {
      const error = await response.json();
      return res.status(response.status).json(error);
    }

    const data = await response.json();
    res.json({
      token: data.token,
      expiresAt: data.expires_at,
    });
  } catch (error) {
    console.error('Failed to generate checkout token:', error);
    res.status(500).json({ error: 'Failed to generate token' });
  }
});

export default router;

Python (FastAPI)

---

Frontend Implementation

Initialize with Token

import { AlternativeClient } from '@getalternative/partner-sdk';

// Fetch token from your backend
const { token } = await fetch('/api/checkout-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ customerId: 'cus_xxx', invoiceId: 'inv_xxx' }),
}).then(res => res.json());

// Initialize SDK
const client = await AlternativeClient.create({
  accessToken: token,
  environment: 'production',
});

Handle Token Expiration

Provide an onAccessTokenExpired callback to automatically refresh tokens:

const client = await AlternativeClient.create({
  accessToken: token,
  environment: 'production',
  onAccessTokenExpired: async () => {
    // This is called when the SDK receives a 401 response
    console.log('Token expired, fetching new one...');

    const response = await fetch('/api/checkout-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ customerId: 'cus_xxx', invoiceId: 'inv_xxx' }),
    });
    const { token } = await response.json();

    return token; // Return the new token
  },
});

If onAccessTokenExpired is not provided and the token expires, the SDK will throw an AccessTokenExpiredError.

---

Error Handling

import { AccessTokenExpiredError } from '@getalternative/partner-sdk';

try {
  // SDK operations
} catch (error) {
  if (error instanceof AccessTokenExpiredError) {
    // Token expired and no refresh callback was provided
    // Redirect user to re-authenticate or show error
    console.error('Session expired. Please refresh the page.');
  }
}

---

Security Best Practices

1. Never expose credentials in frontend code - Always generate tokens on your backend

2. Use HTTPS - Ensure all communication is encrypted

3. Validate on your backend - Verify the customer/invoice belongs to the authenticated user

4. Set appropriate token lifetimes - Shorter lifetimes reduce exposure risk

5. Implement the refresh callback - Provide a smooth experience when tokens expire

---

Token Contents

The checkout token is a JWT that contains:

Claim	Description
partner_id	Your partner identifier
client_id	Your API client ID
customer_id	The customer this token is scoped to
invoice_id	The invoice this token is scoped to
exp	Token expiration timestamp

The SDK automatically extracts customer and invoice information from the token, so you don't need to pass these separately to components.