Developers

Chat & voice API documentation

Astralink Nexus is a hosted REST and WebSocket API. Any platform that can make HTTPS requests can use it: Unity, Android, iOS, consoles and the web. The API is in early access, so details may still change.

Overview

Base URL: https://www.astralink.nexus/api/v1. Requests and responses are JSON. You create a project in your account's API tab and get two keys:

Public key (pk_...): safe to put in a game or web page. Sent in the X-Astralink-Key header. Browsers are limited to the website origins you allow.
Secret key (sk_...): for your server only. Sent as Authorization: Bearer sk_.... Shown once and stored only as a hash.

Your server uses the secret key to vouch for a player and gets back a short-lived user token. The player's device uses that token for everything else.

Public and private IDs

Every player has two identities, kept apart on purpose:

Public ID: assigned by your game or app (random if you like). It is the only ID your game ever sees. A player can stay anonymous with just this.
Private ID: the player's own Astralink account, with an email and password they log into manually. It works across every game and is never sent to your game. Responses only show a display name and a masked email.

When a player logs in, call POST /account/link to sync the account with the public ID they hold in your game. If the account is already linked to another ID in your game, that earlier ID wins, so the player keeps the same identity on any device.

Quick start

1. From your server, vouch for a player and get a token:

curl -X POST https://www.astralink.nexus/api/v1/tokens \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"player-42","display_name":"Dex"}'

2. On the player's device, join a channel (it is created on first use) and send a message:

curl -X POST https://www.astralink.nexus/api/v1/channels/join \
  -H "Authorization: Bearer USER_TOKEN" -H "Content-Type: application/json" \
  -d '{"key":"scene:forest"}'

curl -X POST https://www.astralink.nexus/api/v1/channels/scene:forest/messages \
  -H "Authorization: Bearer USER_TOKEN" -H "Content-Type: application/json" \
  -d '{"text":"hello"}'

Channel keys can be any string your world already uses: 1 to 120 characters of letters, digits and : _ . -.

Endpoints

Method	Path	Who can call it	What it does
GET	`/api/v1/health`	Nobody	Check that the API is reachable.
POST	`/api/v1/tokens`	Secret key	Your server vouches for a player (external_id, display_name) and receives a short-lived user token.
POST	`/api/v1/guest`	Public key	Anonymous guest access with no backend (if you enable guests for the project).
GET	`/api/v1/me`	User token	Who the token belongs to, and whether a private account is linked.
POST	`/api/v1/account/register`	Public key	A player creates their own private Astralink account.
POST	`/api/v1/account/login`	Public key	A player logs in manually and receives a player token.
POST	`/api/v1/account/link`	User token + player token	Sync the private account with the public ID the game assigned.
POST	`/api/v1/account/logout-all`	Public key + player token	Sign the account out on every device.
GET	`/api/v1/channels`	User token	The player's channels, with unread counts.
POST	`/api/v1/channels`	Secret key	Create a group or public channel with an explicit member list.
POST	`/api/v1/channels/join`	User token	Join a channel by key. Public channels are created on first use.
POST	`/api/v1/dm`	User token	Open a private direct-message channel with another player.
GET	`/api/v1/channels/{key}/messages`	User token	History, newest page by default; use after, before and limit to page.
POST	`/api/v1/channels/{key}/messages`	User token	Send a message (up to 2000 characters).
DELETE	`/api/v1/channels/{key}/messages/{seq}`	User token	Delete one of your own messages.
POST	`/api/v1/channels/{key}/read`	User token	Mark a channel read up to a message number.
GET	`/api/v1/channels/{key}/members`	User token	Members of a channel.

History uses a message number (seq) that increases by one in each channel. After a reconnect, ask for ?after=LAST_SEQ to catch up without gaps.

WebSocket (live messages)

Connect to wss://www.astralink.nexus/api/v1/ws?token=USER_TOKEN. Frames are JSON.

// you send
{"op":"join","channel":"scene:forest","after":42}
{"op":"send","channel":"scene:forest","text":"hello","cid":"abc"}
{"op":"typing","channel":"scene:forest"}
{"op":"read","channel":"scene:forest","seq":43}

// you receive
{"op":"ready","user":{...}}
{"op":"joined","channel":{...},"messages":[...],"count":12}
{"op":"message","channel":"scene:forest","seq":43,"text":"hello","user":{...}}
{"op":"ack","cid":"abc","seq":43}
{"op":"typing","channel":"scene:forest","user":{...}}
{"op":"presence","channel":"scene:forest","count":12}
{"op":"error","code":"rate_limited","message":"..."}

Errors and limits

Errors return a non-2xx status and a body like {"error":{"code":"invalid_token","message":"..."}}. Branch on code, which stays stable.

Messages are limited to 2000 characters; excess requests get 429 rate_limited.
User tokens expire (default one hour, set per project). Ask your server for a fresh one when you get 401 invalid_token.
Direct-message and group channels are private to their members; public channels are open to everyone in your project.

Questions? Safe chat for kids covers the parent dashboard, and the FAQ covers the rest.