Skip to main content
The API supports two authentication methods: a shared API key and a JWT Bearer token obtained via Discord OAuth2.

​
API key

Pass your API secret in the x-api-secret request header. The secret is configured on the server via the BOT_API_SECRET environment variable. 
curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/health
API key callers are treated as global admins and bypass per-guild permission checks.
Never expose your API secret in client-side code or public repositories. Rotate it via the BOT_API_SECRET environment variable if it is compromised.

​
JWT Bearer token

The web dashboard uses Discord OAuth2 to obtain a signed JWT. You can use the same flow for programmatic access.
1

Initiate the OAuth2 flow

Redirect the user to the Discord authorization page:
curl -L https://volvox.bot/api/v1/auth/discord
The server redirects to Discord’s OAuth2 authorization page with identify guilds scopes.
2

Handle the callback

After the user authorizes, Discord redirects to GET /api/v1/auth/discord/callback with an authorization code and state parameter. The server:
  1. Validates the CSRF state
  2. Exchanges the code for a Discord access token
  3. Fetches the user’s Discord profile
  4. Creates a signed JWT (HS256, 1-hour expiry)
  5. Sets the token in an httpOnly cookie and redirects to the dashboard
3

Use the Bearer token

Include the JWT in the Authorization header for subsequent requests:
curl -H "Authorization: Bearer YOUR_JWT" \
  https://volvox.bot/api/v1/guilds

​
Get the current user

Verify a token and retrieve the authenticated user’s profile: 
curl -H "Authorization: Bearer YOUR_JWT" \
  https://volvox.bot/api/v1/auth/me

{
  "userId": "123456789012345678",
  "username": "exampleuser",
  "avatar": "abc123def456",
  "guilds": [
    { "id": "987654321", "name": "My Server", "permissions": "8" }
  ]
}

​
Log out

Invalidate the server-side session: 
curl -X POST \
  -H "Authorization: Bearer YOUR_JWT" \
  https://volvox.bot/api/v1/auth/logout

{ "message": "Logged out successfully" }

​
Token expiry

JWT tokens expire after 1 hour. After expiry, re-initiate the OAuth2 flow to obtain a new token. The server-side session is stored in Redis; logging out invalidates it immediately even if the JWT has not expired.

​
Public endpoints

The following endpoints require no authentication:
EndpointDescription
GET /healthBasic health check
GET /statsPublic bot statistics
GET /community/{guildId}/leaderboardXP leaderboard
GET /community/{guildId}/showcasesProject showcase gallery
GET /community/{guildId}/statsCommunity statistics
GET /community/{guildId}/profile/{userId}Public user profile

Build docs developers (and LLMs) love

Get started for freeTalk to us