Omniplex Docs

Authentication

API tokens for bots and servers, user sessions, and scoped sessions.

Most read endpoints are public. Anything that changes data, or posts stats, needs a token in the Authorization header:

Authorization: <token>

You can also prefix the token with what it belongs to, which makes requests easier to read in logs. If you do, the prefix has to match the token:

Authorization: Bot <token>
Authorization: Server <token>
Authorization: Team <token>
Authorization: User <token>

The older Bot-Auth: <token> and User-Auth: <token> headers still work the same way. There's no Server-Auth or Team-Auth header; use Authorization.

Which token to use

You're buildingUse
A bot posting its statsAn API token for the bot
A server posting its member countsAn API token for the server
Anything acting as a personNot possible from outside omniplex.gg (see below)

Our SDKs take the token once and send it for you.

Creating a token

  1. Open your dashboard, find the bot or server on the Bots or Servers tab, and open its API sessions.
  2. Give the token a name (something like "Production bot") and pick how long it lasts: 1 hour, 1 day, 7 days, 30 days or 1 year.
  3. Optionally, tick Restrict permissions and choose only the permissions the token needs. A restricted token can never do more than you can yourself.
  4. Create it and copy the token straight away. It's only shown once.

Every token is listed with its name, expiry and permissions, so you can tell them apart later. To create tokens from code instead, see Scoped sessions.

Keeping tokens safe

  • Treat a token like a password. Don't commit it to a public repository, paste it in Discord, or put it in client-side code.
  • Store it in an environment variable or your host's secret storage.
  • Restrict permissions for anything that only needs to do one job.
  • Prefer an expiry over a token that lasts forever, and create a new one before the old one expires.

If a token leaks, open API sessions for the same bot or server and revoke it. It stops working immediately. Then create a new one and update your bot. If you think someone used a leaked token to change your listing, open a support ticket.

User sessions

A user session is what you get by signing in to omniplex.gg. It's only accepted from omniplex.gg itself: Popplio rejects a user session sent from any other origin (with an exception for Bug Hunters testing preview builds), and the login endpoint only works with the official site. Third-party apps can't sign users in or act on their behalf, so build integrations on bot or server tokens.

On omniplex.gg, the session lives in an HttpOnly popplio_session cookie that page scripts can't read, and the site calls the API through its own host. Signing out calls POST /auth/logout, which ends the session on the server and clears the cookie.

Scoped sessions

To hand a token to something that should do less than you can, create a scoped session with only the permissions it needs:

POST /{target_type}/{target_id}/sessions

Requires the Manage API Sessions permission on the target (bot, server, team or pack). Body:

{
  "name": "My integration",
  "type": "api",
  "perm_limits": ["edit_bots"],
  "expiry": 604800
}
FieldTypeNotes
namestringA label so you can recognise the session later.
typestringMust be api. Login sessions can't be created here.
perm_limitsstring[]The permissions the session may use. Empty is only allowed if you hold the owner permission on the target, in which case the session gets full access.
expirynumberHow long the session lasts, in seconds.

The response includes the session's token. It's only shown once; there's no way to read it back afterwards.

{
  "target_id": "1234567890",
  "token": "...",
  "session_id": "..."
}

Managing sessions

GET    /{target_type}/{target_id}/sessions
DELETE /{target_type}/{target_id}/sessions/{session_id}

Listing needs View API Sessions and revoking needs Manage API Sessions. A listed session never includes its token, only its name, type, permission limits and expiry, so if you lose a token, revoke it and create a new one.

Testing a token

POST /auth/test
{ "auth_type": "bot", "target_id": "1234567890123456789", "token": "..." }

Returns whether the token is valid for that bot, server, team or user, without using it on a real request.

On this page