ARRR Network

API Keys ​

This guide is for project owners: people building an app on the network. An API key is what lets your app create rooms. Without one, the public network does not hand out nodes, so not just anyone can spend the mesh's capacity under a name nobody registered.

1. Log in at cloud.arrr.fun ​

Go to https://cloud.arrr.fun and create an account (or log in). The cloud console serves both kinds of account; when it asks, choose the app owner side. You can switch later, it only decides which page you land on.

2. Create an app ​

On the Apps page click Create App and give it a name. The app id you choose here is the appId you pass to the SDK. Rooms, connected clients and keys are all grouped under it.

One app opens on three tabs:

tabwhat is on it
Overviewrooms open and players connected right now, and how the app is configured: tick rate, whether players must sign in, what signed-out players may do, and the origins sign-in may redirect to
API keythe one key this app ships with - generate it, see when it was last used, revoke it
Roomsthe rooms open right now, which node holds authority over each, and how many replicas it has

NPCs are not among them. They belong to your account rather than to any one app, and every app you own can call every NPC you own, so they have a page of their own.

3. Generate a key ​

Open the app, go to its API key tab and click Generate API Key. The key looks like arrr_… and is shown once, so copy it right away. The console stores only a hash, and cannot show it to you again; if you lose it, revoke it and generate another.

4. Pass it to connect() ​

The console does not repeat this snippet on the app's page: it lives here, where it can be linked and searched. The app id is on that page, under the app's name.

html
<script src="https://www.arrr.fun/sdk/arrr-network.iife.js"></script>
<script>
  const room = await arrrNetwork.connect('lobby', {
    appId: 'my-app',
    apiKey: 'arrr_…',   // from the cloud console → Apps
    onMessage(data, seq) { /* ... */ }
  });
</script>
javascript
import { connect } from 'arrr-network';

const room = await connect('lobby', {
  appId: 'my-app',
  apiKey: process.env.ARRR_API_KEY,   // from the cloud console → Apps
  onMessage(data, seq) { /* ... */ }
});

The SDK sends the key as an x-api-key header when it asks the network which node should host the room. The key must belong to the app named in appId; a key for a different app is refused rather than silently treated as anonymous, because a wrong key is a misconfiguration you want to see.

For local development against your own copy of the service, no key is needed: a self-hosted service defaults to APP_REGISTRATION=open, which accepts keyless connections and creates unknown apps on the fly. The public network runs in key mode.

What the key does and doesn't protect ​

A browser app ships its key to every visitor, so anyone who opens devtools can read it. The key is therefore not a secret and the gate is not secrecy. What it does is three smaller things:

  • Attribution. Every room belongs to an app somebody registered and can be held to.
  • Revocation. Delete the key in the console and every client built with it stops getting nodes.
  • Stops the cheapest abuse. A stranger cannot spend node capacity under an unregistered name with no account at all.

It does not identify individual players, and it does not stop a determined person from connecting as your app. If your app needs per-user identity, use the app's own user auth flow in the SDK (auth, join tokens); that runs on top of the key and is not replaced by it.

Account tokens: the console over REST ​

An app's key speaks for one app. For a script or an agent that should do what you do in the console - create apps, keys and NPCs, read usage - create an account token under API. It looks like arrr_acct_…, is shown once, goes in Authorization: Bearer … on every console endpoint, and is revoked on its own. Keep it on a server; it must never ship in a client.

Revoking a key ​

On the app's page in the console, click Revoke next to the key. Clients already in a room keep their current connection; new connections made with that key are refused as soon as the revocation lands. Generate a new key first and ship it, then revoke the old one, if you want a clean rotation.

Deleting the app itself deletes all of its keys.

Next steps ​