Authentication - SW Combine SDK

The SW Combine SDK supports three client modes, each suited to a different level of access. You choose a mode by what you pass to the SWCombine constructor. Public endpoints work with no credentials at all; most game data endpoints require an access token; and the full OAuth flow — including automatic token refresh — requires your OAuth app credentials.

The three client modes

Public (no credentials)
Token-only
Full OAuth

Pass no arguments to get a client that can call public endpoints without any authentication. Use this for endpoints like character.getByHandle that resolve public data without a token.

import { SWCombine } from 'swcombine-sdk';

const client = new SWCombine();

Authenticated endpoints will throw a 401 Unauthorized error when called from a public client.

Pass an existing access token string to authenticate requests. The SDK injects it as an Authorization: OAuth {token} header on every request. Use this when you already have a token and don’t need to run OAuth flows or refresh automatically.

import { SWCombine } from 'swcombine-sdk';

const client = new SWCombine({
  token: process.env.SWC_ACCESS_TOKEN!,
});

If the token expires, requests will fail with a 401 — the SDK cannot refresh automatically without OAuth credentials.

Pass clientId, clientSecret, and optionally a redirectUri to unlock the full OAuth flow: generate authorization URLs, handle callbacks, and refresh tokens automatically when they expire.

import { SWCombine, AccessType } from 'swcombine-sdk';

const client = new SWCombine({
  clientId: process.env.SWC_CLIENT_ID!,
  clientSecret: process.env.SWC_CLIENT_SECRET!,
  redirectUri: 'http://localhost:3000/callback',
  accessType: AccessType.Offline, // Request a refresh token
  token: process.env.SWC_ACCESS_TOKEN,  // Optional: seed with an existing token
});

You must provide both clientId and clientSecret together. The SDK throws immediately if only one is set.

ClientConfig reference

Every option you can pass to new SWCombine(config):

clientId

string

Your OAuth application’s client ID. Must be provided together with clientSecret.

clientSecret

string

Your OAuth application’s client secret. Must be provided together with clientId.

redirectUri

string

The callback URL registered with your OAuth application. Required for auth.getAuthorizationUrl() and auth.handleCallback(). Must match exactly what you registered — including scheme, host, port, and path.

accessType

AccessType

Controls whether the authorization server returns a refresh token. Use AccessType.Offline to receive a refresh token for long-lived access; AccessType.Online (default) returns only an access token.

token

string | OAuthToken

An existing token to seed the client with. Can be a raw access token string or a full OAuthToken object (accessToken, refreshToken, expiresAt). The SDK uses this immediately without running an OAuth flow.

baseURL

string

Override the API base URL. Defaults to https://www.swcombine.com/ws/v2.0/. Most applications do not need this.

timeout

number

Request timeout in milliseconds. Defaults to 30000 (30 seconds).

maxRetries

number

Maximum number of retry attempts for retryable errors (network failures, 5xx responses, rate limit hits). Defaults to 3.

retryDelay

number

Base delay between retry attempts in milliseconds, applied with exponential backoff. Defaults to 1000.

debug

boolean

When true, logs all HTTP requests and responses to the console. Useful during development. Defaults to false.

Which endpoints need which mode

Mode	Required for
Public (no credentials)	`character.getByHandle`, `galaxy.`, `types.`, `news.*`, `api.helloWorld`, `api.time`
Token-only	`character.get`, `character.me()`, `faction.`, `inventory.`, `market.`, `events.`, `location.`, `datacard.`
Full OAuth	`auth.getAuthorizationUrl()`, `auth.handleCallback()`, `auth.revokeToken()`, `client.refreshToken()`

Automatic token refresh only works in full OAuth mode. In token-only mode, you must supply a fresh token manually after expiry.

Next steps

OAuth flow

Step-by-step guide to registering your app, running the authorization flow, and handling callbacks.

Scopes

Browse all 170+ scope constants and learn how to request only the permissions you need.

Token management

Store, inspect, refresh, and revoke tokens in your application.

Quickstart

Make your first API call in under five minutes.

Documentation Index

​The three client modes

​ClientConfig reference

​Which endpoints need which mode

​Next steps

OAuth flow

Scopes

Token management

Quickstart

The three client modes

ClientConfig reference

Which endpoints need which mode

Next steps