Character

The client.character resource gives you access to the core player identity in the Star Wars Combine universe. You can look up characters by UID or handle, read the authenticated user’s own profile, exchange in-game messages, transfer credits, and inspect the fine-grained privilege and permission system.

character.get()

Get character by UID. Returns the Character object directly — not wrapped in a Page. Requires: CHARACTER_READ

string

required

The uid parameter.

const character = await client.character.get({ uid: '1:12345' });
console.log(character.name); // access properties directly, not character.data

character.getByHandle()

Look up a character’s UID by their handle (username). This endpoint is public — no authentication required — and is the primary way to resolve a handle to the uid used by every other character endpoint.

string

required

The handle parameter.

const { uid, handle } = await client.character.getByHandle({ handle: 'Dreks Selmur' });
console.log(uid);    // "1:46931"
console.log(handle); // "Dreks Selmur"

// Chain into a full profile fetch (requires CHARACTER_READ)
const character = await client.character.get({ uid });

character.hasPermission()

Check if the API client has a specific permission for this character

string

required

Permission scope to check (e.g., ‘CHARACTER_READ’, ‘MESSAGES_SEND’)

string

required

Character UID

const canRead = await client.character.hasPermission({ uid: '1:12345', permission: 'CHARACTER_READ' });
if (canRead) {
  const character = await client.character.get({ uid: '1:12345' });
}

character.me()

Get the currently authenticated user’s character Requires: CHARACTER_READ

const myCharacter = await client.character.me();

Credit Log

character.creditlog.list()

Get character’s credit log (paginated) Requires: CHARACTER_CREDITS

**item\_count**: number

default:"50"

Number of items to retrieve. Default: 50, Max: 1000

number

Milliseconds to wait before fetching each subsequent page. Helps avoid rate limits during auto-pagination.

**start\_id**: number

Oldest transaction ID threshold (1 = oldest 1000, 0/default = newest 1000)

**start\_index**: number

default:"1"

Starting position for pagination (1-based). Default: 1

string

required

The uid parameter.

const creditlog = await client.character.creditlog.list({ uid: '1:12345' });
const moreLogs = await client.character.creditlog.list({ uid: '1:12345', start_index: 51, item_count: 100 });
const oldestLogs = await client.character.creditlog.list({ uid: '1:12345', start_id: 1 });
// Fetch up to 1000 credit log entries at once
const manyLogs = await client.character.creditlog.list({ uid: '1:12345', item_count: 1000 });

// Iterate through all pages automatically
for await (const entry of creditlog) {
  console.log(entry);
}

Credits

character.credits.get()

Get character’s credit balance Requires: CHARACTER_CREDITS

string

required

The uid parameter.

const credits = await client.character.credits.get({ uid: '1:12345' });
console.log(`Credits: ${credits}`); // Credits: 320089347

character.credits.transfer()

Transfer credits from character to another character or faction

number

required

Amount to transfer

string

Reason for transfer (optional, API will auto-append client name) @requires_auth Yes @requires_scope CHARACTER_CREDITS_WRITE

string

required

Recipient character or faction name/UID (REQUIRED)

string

required

Character UID

Messages

character.messages.create()

Send a message Requires: MESSAGES_SEND

string

required

Message text content

string

required

Semicolon-separated list of recipient character handles (max 25). Example: ‘handle1;handle2’

string

required

The uid parameter.

// Valid: handles
await client.character.messages.create({
  uid: '1:12345',
  receivers: 'recipient_handle_1;recipient_handle_2',
  communication: 'Hello from the SDK!'
});

// Invalid: UIDs are rejected by the API and pre-validated by this SDK
await client.character.messages.create({
  uid: '1:12345',
  receivers: '1:12345',
  communication: 'Test'
});

character.messages.delete()

Delete a message Requires: MESSAGES_DELETE

string

required

The messageId parameter.

string

required

The uid parameter.

character.messages.get()

Get a specific message Requires: MESSAGES_READ

string

required

The messageId parameter.

string

required

The uid parameter.

import { MessageMode } from 'swcombine-sdk';

const messages = await client.character.messages.list({ uid: '1:12345', mode: MessageMode.Received });
const messageId = messages.data[0]?.attributes.uid;

if (messageId) {
  const message = await client.character.messages.get({ uid: '1:12345', messageId });
  console.log(message.communication);
}

character.messages.list()

List messages sent or received by character (paginated) Note: list responses return MessageListItem[] metadata objects and do not guarantee a communication field. Use get() for full message content. Requires: MESSAGES_READ

**item\_count**: number

The item_count parameter.

MessageMode

Message mode: MessageMode.Sent or MessageMode.Received. If omitted, returns both sent and received messages.

number

Milliseconds to wait before fetching each subsequent page. Helps avoid rate limits during auto-pagination.

**start\_index**: number

The start_index parameter.

string

required

The uid parameter.

import { MessageMode } from 'swcombine-sdk';

const allMessages = await client.character.messages.list({ uid: '1:12345' });
const received = await client.character.messages.list({ uid: '1:12345', mode: MessageMode.Received });
const moreMessages = await client.character.messages.list({ uid: '1:12345', mode: MessageMode.Received, start_index: 51, item_count: 50 });

const firstMessageId = received.data[0]?.attributes.uid;
if (firstMessageId) {
  const detail = await client.character.messages.get({ uid: '1:12345', messageId: firstMessageId });
  console.log(detail.communication);
}

// Iterate through all pages automatically
for await (const msg of allMessages) {
  console.log(msg.attributes.uid);
}

Permissions

character.permissions.getScopes()

Get flat list of granted scope names

string

required

The uid parameter.

character.permissions.list()

Get permissions granted to API client for this character

string

required

The uid parameter.

const perms = await client.character.permissions.list({ uid: '1:12345' });
const scopes = perms.permission[0]?.scopes.scope || [];
console.log('Granted scopes:', scopes.join(', '));

Privileges

character.privileges.get()

Get a specific privilege. Returns the PrivilegeDetail object directly — not wrapped in a Page. Requires: CHARACTER_PRIVILEGES

number

Optional faction ID to view privileges for (defaults to token owner’s primary faction)

string

required

Privilege name

string

required

Privilege group name

string

required

Character UID

character.privileges.list()

Get character’s privileges organized by group Requires: CHARACTER_PRIVILEGES

string

required

The uid parameter.

const privs = await client.character.privileges.list({ uid: '1:12345' });
privs.privilegegroup.forEach(g => {
  console.log(`${g.attributes.name}: ${g.attributes.count} privileges`);
});

character.privileges.update()

Update a specific privilege (grant or revoke) Throws a validation SWCError carrying the API’s reason when the change is refused (for example “Requires powered HQ to change privileges”). The API reports that with HTTP 200 and a failure list rather than an error status.

number

Optional ID of the faction the privilege is granted or revoked in (defaults to token owner’s primary faction; required if the token owner is a freelancer)

string

required

Privilege name

string

required

Privilege group name

boolean

Set to true to revoke the privilege, false/undefined to grant it

string

required

Character UID

Skills

character.skills.list()

Get character’s skills organized by category Requires: CHARACTER_SKILLS

string

required

The uid parameter.

const skills = await client.character.skills.list({ uid: '1:12345' });
skills.general?.[0].skill.forEach(s => console.log(s.attributes.type, s.value));

Faction

Access faction membership, budgets, and credit logs.

Inventory

List and manage entities owned or piloted by a character.

Events

Query the event log for character activity.

Authentication scopes

See the full list of OAuth scopes and what they unlock.

Get Started

Authentication

Core Concepts

API Resources

character.get()

character.getByHandle()

character.hasPermission()

character.me()

Credit Log

character.creditlog.list()

Credits

character.credits.get()

character.credits.transfer()

Messages

character.messages.create()

character.messages.delete()

character.messages.get()

character.messages.list()

Permissions

character.permissions.getScopes()

character.permissions.list()

Privileges

character.privileges.get()

character.privileges.list()

character.privileges.update()

Skills

character.skills.list()

Faction

Inventory

Events

Authentication scopes

​character.get()

​character.getByHandle()

​character.hasPermission()

​character.me()

​Credit Log

​character.creditlog.list()

​Credits

​character.credits.get()

​character.credits.transfer()

​Messages

​character.messages.create()

​character.messages.delete()

​character.messages.get()

​character.messages.list()

​Permissions

​character.permissions.getScopes()

​character.permissions.list()

​Privileges

​character.privileges.get()

​character.privileges.list()

​character.privileges.update()

​Skills

​character.skills.list()

​Related resources

Faction

Inventory

Events

Authentication scopes

character.get()

character.getByHandle()

character.hasPermission()

character.me()

Credit Log

character.creditlog.list()

Credits

character.credits.get()

character.credits.transfer()

Messages

character.messages.create()

character.messages.delete()

character.messages.get()

character.messages.list()

Permissions

character.permissions.getScopes()

character.permissions.list()

Privileges

character.privileges.get()

character.privileges.list()

character.privileges.update()

Skills

character.skills.list()

Related resources