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. Most methods require the CHARACTER_READ OAuth scope; the getByHandle method is the only publicly available endpoint that needs no authentication at all.

Character profile methods

me()

Fetches the full profile for the character associated with the current access token. No UID required. Requires: CHARACTER_READ

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

console.log(me.name); // "Luke Skywalker"
console.log(me.credits); // 42000
console.log(me.faction); // faction info object

get()

Fetches the full profile for any character by UID. Requires: CHARACTER_READ

string

required

The character’s unique identifier in "type:id" format, e.g. "1:12345".

const character = await client.character.get({ uid: '1:12345' });

console.log(character.name);
console.log(character.faction);

getByHandle()

Resolves a character’s handle (username) to their UID. This endpoint is public — no access token or authentication is needed.

string

required

The character’s in-game handle (username), e.g. "luke-skywalker".

// No auth needed — works with a public client
const publicClient = new SWCombine();

const { uid, handle } = await publicClient.character.getByHandle({
  handle: 'luke-skywalker',
});

console.log(uid); // "1:12345"
console.log(handle); // "luke-skywalker"

Use getByHandle to resolve a known handle to a UID before making authenticated calls. This is safe to call without any credentials.

hasPermission()

Checks whether a character holds a specific permission. Requires: CHARACTER_READ

string

required

The character UID to check.

string

required

The permission name to test.

const allowed = await client.character.hasPermission({
  uid: '1:12345',
  permission: 'MANAGE_FACTION',
});

if (allowed) {
  console.log('Character has permission');
}

Messages

The client.character.messages sub-resource lets you list, read, send, and delete in-game messages for a character.

messages.list()

Returns a paginated list of messages for a character’s inbox or sent box.

string

required

The character UID whose messages to list.

MessageMode

Filter by message direction. Use MessageMode.Sent or MessageMode.Received. Omit to return both sent and received messages.

number

default:"1"

1-based index of the first item to return.

number

default:"50"

Number of items per page.

import { MessageMode } from 'swcombine-sdk';

// List received messages
const inbox = await client.character.messages.list({
  uid: '1:12345',
  mode: MessageMode.Received,
});

// List sent messages
const sent = await client.character.messages.list({
  uid: '1:12345',
  mode: MessageMode.Sent,
});

for await (const msg of inbox) {
  console.log(msg.subject, msg.sender);
}

messages.get()

Fetches the full content of a single message.

string

required

The character UID.

string

required

The ID of the message to retrieve.

const message = await client.character.messages.get({
  uid: '1:12345',
  messageId: 'msg-789',
});

console.log(message.subject);
console.log(message.body);

messages.create()

Sends a new in-game message to one or more recipients.

string

required

The sending character’s UID.

string

required

A semicolon-separated list of recipient handles (not UIDs). Maximum 25 recipients.

string

required

The message text content to send.

The receivers field takes character handles separated by semicolons, not UIDs. Sending to UIDs will fail. Maximum 25 recipients per message.

const message = await client.character.messages.create({
  uid: '1:12345',
  receivers: 'han-solo;leia-organa',
  communication: 'Meeting at the cantina — be there at 0800.',
});

messages.delete()

Deletes a message.

string

required

The character UID.

string

required

The ID of the message to delete.

await client.character.messages.delete({
  uid: '1:12345',
  messageId: 'msg-789',
});

Skills

skills.list()

Returns all skills for a character, including current levels and experience.

string

required

The character UID.

const skills = await client.character.skills.list({ uid: '1:12345' });

console.log(skills.piloting);
console.log(skills.combat);

Credits

credits.get()

Returns the current credit balance for a character.

string

required

The character UID.

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

credits.transfer()

Transfers credits from the authenticated character to a recipient.

string

required

The sending character’s UID.

number

required

The number of credits to transfer.

string

required

The recipient character’s UID.

string

An optional note or reason for the transfer, recorded in the credit log.

Credit transfers are irreversible. Double-check the recipient UID before executing.

await client.character.credits.transfer({
  uid: '1:12345',
  amount: 10000,
  recipient: '1:67890',
  reason: 'Payment for ship repairs',
});

creditlog.list()

Returns a paginated history of credit transactions for a character.

string

required

The character UID.

number

default:"1"

1-based index of the first entry to return.

number

default:"50"

Number of entries per page.

number

Optional transaction ID threshold. Use 1 for oldest 1000 entries; 0 or omit for the newest 1000.

const log = await client.character.creditlog.list({ uid: '1:12345' });

for await (const entry of log) {
  console.log(entry.amount, entry.description, entry.timestamp);
}

Privileges

The privileges system controls what actions a character can perform, optionally scoped to a faction.

privileges.list()

Lists all privilege groups and their entries for a character.

string

required

The character UID.

string

Optional faction UID to scope privilege results to a specific faction.

const privs = await client.character.privileges.list({ uid: '1:12345' });

privileges.get()

Returns the detail of a specific privilege for a character.

string

required

The character UID.

string

required

The privilege group name.

string

required

The privilege name within the group.

string

Optional faction UID to scope the query.

const detail = await client.character.privileges.get({
  uid: '1:12345',
  privilegeGroup: 'faction',
  privilege: 'MANAGE_MEMBERS',
});

privileges.update()

Grants or revokes a specific privilege for a character.

string

required

The character UID.

string

required

The privilege group name.

string

required

The privilege name within the group.

boolean

Set to true to revoke the privilege. Omit or set to false to grant it.

string

Optional faction UID to scope the update.

// Grant a privilege
await client.character.privileges.update({
  uid: '1:12345',
  privilegeGroup: 'faction',
  privilege: 'MANAGE_MEMBERS',
});

// Revoke a privilege
await client.character.privileges.update({
  uid: '1:12345',
  privilegeGroup: 'faction',
  privilege: 'MANAGE_MEMBERS',
  revoke: true,
});

Permissions

permissions.list()

Returns all OAuth permissions associated with a character’s token.

string

required

The character UID.

const perms = await client.character.permissions.list({ uid: '1:12345' });

permissions.getScopes()

Returns the list of OAuth scope strings granted for the character’s current token.

string

required

The character UID.

const scopes = await client.character.permissions.getScopes({ uid: '1:12345' });

console.log(scopes); // ["CHARACTER_READ", "CREDITS_WRITE", ...]

Use getScopes() to verify at runtime that your token has the scopes needed before calling protected endpoints.

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 profile methods

me()

get()

getByHandle()

hasPermission()

Messages

messages.list()

messages.get()

messages.create()

messages.delete()

Skills

skills.list()

Credits

credits.get()

credits.transfer()

creditlog.list()

Privileges

privileges.list()

privileges.get()

privileges.update()

Permissions

permissions.list()

permissions.getScopes()

Faction

Inventory

Events

Authentication scopes

​Character profile methods

​me()

​get()

​getByHandle()

​hasPermission()

​Messages

​messages.list()

​messages.get()

​messages.create()

​messages.delete()

​Skills

​skills.list()

​Credits

​credits.get()

​credits.transfer()

​creditlog.list()

​Privileges

​privileges.list()

​privileges.get()

​privileges.update()

​Permissions

​permissions.list()

​permissions.getScopes()

​Related resources

Faction

Inventory

Events

Authentication scopes

Character profile methods

me()

get()

getByHandle()

hasPermission()

Messages

messages.list()

messages.get()

messages.create()

messages.delete()

Skills

skills.list()

Credits

credits.get()

credits.transfer()

creditlog.list()

Privileges

privileges.list()

privileges.get()

privileges.update()

Permissions

permissions.list()

permissions.getScopes()

Related resources