Skip to main content
OAuth scopes tell SW Combine what your application is allowed to do on a user’s behalf. When you generate an authorization URL, the scopes you include determine which endpoints you can call and which actions you can take with the resulting token. Requesting fewer scopes limits your app’s footprint and builds user trust — users see the full permission list before they authorize.

​
Using scope constants

The SDK exports typed constants for every scope. Using them instead of raw strings gives you IDE autocomplete, compile-time typo detection, and a single source of truth if scope names ever change: 
import { SWCombine, CharacterScopes, MessageScopes } from 'swcombine-sdk';

const client = new SWCombine({
  clientId: process.env.SWC_CLIENT_ID!,
  clientSecret: process.env.SWC_CLIENT_SECRET!,
  redirectUri: 'http://localhost:3000/callback',
});

const authUrl = client.auth.getAuthorizationUrl({
  scopes: [
    CharacterScopes.READ,    // 'character_read'
    CharacterScopes.STATS,   // 'character_stats'
    MessageScopes.READ,      // 'messages_read'
    MessageScopes.SEND,      // 'messages_send'
  ],
  state: 'your-csrf-state-value',
});
All scope values sent to the API are lowercase strings with underscores (e.g., character_read, personal_inv_ships_all). The constants resolve to these lowercase literals automatically. The API rejects uppercase scope strings.

​
Scope categories

Import: import { CharacterScopes } from 'swcombine-sdk'
ConstantValueWhat it grants
CharacterScopes.AUTHcharacter_authCharacter name and ID only, for identity verification
CharacterScopes.READcharacter_readUID, handle, image, race, gender (and more if profile is public)
CharacterScopes.STATScharacter_statsHP and XP
CharacterScopes.PRIVILEGEScharacter_privilegesCharacter privileges
CharacterScopes.SKILLScharacter_skillsCharacter skills
CharacterScopes.CREDITScharacter_creditsCredit balance (read-only)
CharacterScopes.CREDITS_WRITEcharacter_credits_writeTransfer credits
CharacterScopes.FORCEcharacter_forceForce points, FXP, regen rate, Force Meter
CharacterScopes.LOCATIONcharacter_locationIn-game location
CharacterScopes.EVENTScharacter_eventsCharacter event log
CharacterScopes.ALLcharacter_allAll character permissions
Import: import { MessageScopes } from 'swcombine-sdk'
ConstantValueWhat it grants
MessageScopes.READmessages_readRead messages sent to or by the character
MessageScopes.SENDmessages_sendSend messages
MessageScopes.DELETEmessages_deleteDelete messages
MessageScopes.ALLmessages_allRead, send, and delete messages
Import: import { Scopes } from 'swcombine-sdk'Personal inventory scopes follow the pattern Scopes.PersonalInventory.{ENTITY}.{ACTION}. The top-level overview scope gives access to inventory summary data.
Scopes.PersonalInventory.OVERVIEW          // 'personal_inv_overview'

// Ships
Scopes.PersonalInventory.SHIPS.READ        // 'personal_inv_ships_read'
Scopes.PersonalInventory.SHIPS.RENAME      // 'personal_inv_ships_rename'
Scopes.PersonalInventory.SHIPS.ASSIGN      // 'personal_inv_ships_assign'
Scopes.PersonalInventory.SHIPS.MAKEOVER    // 'personal_inv_ships_makeover'
Scopes.PersonalInventory.SHIPS.TAGS_READ   // 'personal_inv_ships_tags_read'
Scopes.PersonalInventory.SHIPS.TAGS_WRITE  // 'personal_inv_ships_tags_write'
Scopes.PersonalInventory.SHIPS.ALL         // 'personal_inv_ships_all'
The same actions (READ, RENAME, ASSIGN, MAKEOVER, TAGS_READ, TAGS_WRITE, ALL) are available for: VEHICLES, STATIONS, CITIES, FACILITIES, ITEMS, DROIDS, MATERIALS, CREATURES. Planets have a reduced set (READ, ASSIGN, TAGS_READ, TAGS_WRITE, ALL); NPCs don’t have RENAME.
Import: import { FactionScopes } from 'swcombine-sdk'
ConstantValueWhat it grants
FactionScopes.READfaction_readBasic faction information
FactionScopes.MEMBERSfaction_membersFaction members list
FactionScopes.STOCKSfaction_stocksStocks owned by the faction
FactionScopes.CREDITS_READfaction_credits_readFaction credit balance
FactionScopes.CREDITS_WRITEfaction_credits_writeTransfer faction credits
FactionScopes.BUDGETS_READfaction_budgets_readFaction budget details
FactionScopes.BUDGETS_WRITEfaction_budgets_writeModify faction budgets
FactionScopes.DATACARDS_READfaction_datacards_readFaction datacard assignments
FactionScopes.DATACARDS_WRITEfaction_datacards_writeAssign or revoke datacards
FactionScopes.ALLfaction_allAll faction permissions
Import: import { Scopes } from 'swcombine-sdk'Faction inventory scopes mirror the personal inventory structure under Scopes.FactionInventory:
Scopes.FactionInventory.OVERVIEW             // 'faction_inv_overview'

// Faction ships
Scopes.FactionInventory.SHIPS.READ           // 'faction_inv_ships_read'
Scopes.FactionInventory.SHIPS.RENAME         // 'faction_inv_ships_rename'
Scopes.FactionInventory.SHIPS.ASSIGN         // 'faction_inv_ships_assign'
Scopes.FactionInventory.SHIPS.MAKEOVER       // 'faction_inv_ships_makeover'
Scopes.FactionInventory.SHIPS.TAGS_READ      // 'faction_inv_ships_tags_read'
Scopes.FactionInventory.SHIPS.TAGS_WRITE     // 'faction_inv_ships_tags_write'
Scopes.FactionInventory.SHIPS.ALL            // 'faction_inv_ships_all'
The full set of entity types mirrors the personal inventory: SHIPS, VEHICLES, STATIONS, CITIES, FACILITIES, PLANETS, ITEMS, NPCS, DROIDS, MATERIALS, CREATURES.

​
Helper functions

The SDK provides four helper functions that return pre-built scope arrays for common scenarios: 
import {
  getMinimalScopes,
  getReadOnlyScopes,
  getAllScopes,
  getAllCharacterScopes,
  getAllMessageScopes,
  getAllPersonalInventoryScopes,
  getAllFactionScopes,
  getAllFactionInventoryScopes,
} from 'swcombine-sdk';
FunctionReturnsUse case
getMinimalScopes()['character_auth', 'character_read']Login / identity verification only
getReadOnlyScopes()Character read, stats, skills, credits, messages read, inventory overview, faction readAnalytics dashboards and read-only integrations
getAllCharacterScopes()All CharacterScopes.* valuesCharacter management tools
getAllMessageScopes()All MessageScopes.* valuesFull messaging access
getAllPersonalInventoryScopes()All PersonalInventoryScopes.* valuesPersonal asset management
getAllFactionScopes()All FactionScopes.* valuesFaction administration
getAllFactionInventoryScopes()All FactionInventoryScopes.* valuesFaction asset management
getAllScopes()All 170+ scopes across every categoryDevelopment and testing only
The SW Combine API does not support scope inheritance. Requesting CharacterScopes.ALL (character_all) does not include CharacterScopes.READ (character_read) — you must list both explicitly if you want comprehensive access.

​
Common scope combinations

import { getMinimalScopes } from 'swcombine-sdk';

const authUrl = client.auth.getAuthorizationUrl({
  scopes: getMinimalScopes(), // ['character_auth', 'character_read']
  state,
});

import { CharacterScopes } from 'swcombine-sdk';

const scopes = [
  CharacterScopes.READ,
  CharacterScopes.STATS,
  CharacterScopes.SKILLS,
  CharacterScopes.FORCE,
  CharacterScopes.LOCATION,
];

import { CharacterScopes, MessageScopes } from 'swcombine-sdk';

const scopes = [
  CharacterScopes.READ,
  MessageScopes.READ,
  MessageScopes.SEND,
  MessageScopes.DELETE,
];

import { CharacterScopes, Scopes } from 'swcombine-sdk';

const scopes = [
  CharacterScopes.READ,
  Scopes.PersonalInventory.OVERVIEW,
  Scopes.PersonalInventory.SHIPS.ALL,
  Scopes.PersonalInventory.VEHICLES.ALL,
];

import { FactionScopes, Scopes } from 'swcombine-sdk';

const scopes = [
  FactionScopes.ALL,
  Scopes.FactionInventory.OVERVIEW,
  Scopes.FactionInventory.SHIPS.READ,
  Scopes.FactionInventory.VEHICLES.READ,
];

import { getReadOnlyScopes } from 'swcombine-sdk';

const authUrl = client.auth.getAuthorizationUrl({
  scopes: getReadOnlyScopes(),
  state,
});

​
TypeScript type safety

The SDK exports an AllScopes type — a union of every valid scope literal — so TypeScript catches invalid scope strings at compile time: 
import type { AllScopes } from 'swcombine-sdk';
import { CharacterScopes, MessageScopes } from 'swcombine-sdk';

// TypeScript enforces that every item is a valid scope literal
const scopes: AllScopes[] = [
  CharacterScopes.READ,   // OK — autocomplete suggests all character scopes
  MessageScopes.SEND,     // OK — autocomplete suggests all message scopes
  // 'not_a_scope',       // Error: not assignable to type 'AllScopes'
  // CharacterScopes.TYPO // Error: property 'TYPO' does not exist
];