Skip to content
Ball2DDocs

Get started

Create an API key

Authorize a server to open rooms for your Ball2D account.

Every room opened from Node.js needs an API key. A key identifies your account to the Ball2D service, which uses it to admit rooms and enforce your room limits.

Sign in

Open your Ball2D account and sign in. Google, GitHub, Steam and email accounts all work.

Create the key

In Room hosting, enter a name that tells you where the key is used, such as Production host, and choose when it expires: 7, 30, 90 or 365 days. Select Create API key.

Save it now

The full key is shown once. Copy it into your server's secret store before you dismiss it; Ball2D keeps only a hash and cannot show it again. Keys begin with b2d_.

Give it to your server

Pass the key to your process as an environment variable. The examples in these docs read BALL2D_API_KEY.

Terminal
export BALL2D_API_KEY="b2d_…"
node host.mjs

Keep keys on your server

An API key lets its holder open rooms on your account. Keep it where only your host process can read it:

  • Store it in your platform's secret manager or an environment file that is not committed.
  • Never put it in browser code, a room name, a chat message or an invitation link.
  • Use one key per deployment, so you can revoke one without stopping the others.

The SDK sends the key only to the configured service, in an Authorization header over HTTPS. It is never sent to players.

Limits

An account can hold two active keys. Each key can run one room at a time, and an account can run two. Admission and limits lists every limit.

Revoke a key

Select Revoke next to a key in your account. Ball2D disables the key and closes the rooms it opened before it reports success. If cleanup cannot finish, the key stays revoked and shows Retry room cleanup; select it to finish closing the rooms.

Revoking a key stops its rooms through the Ball2D service. Players who are already connected directly to a modified host could keep exchanging packets until that host stops; revocation is not a remote kill switch.

When a key expires, its rooms close the same way. Create a replacement key before the old one expires and roll it out with your next deployment.