Authentication - BotNexus Docs
Discover, Manage, and Scale Discord Bots
Authorization Sequence & Scope Mapping
BotNexus implements a standard authorization code flow with PKCE to secure developer access to guild management endpoints.
Initiate the handshake by directing users to https://auth.botnexus.dev/oauth2/authorize with your registered client ID, redirect URI, and a cryptographically secure code verifier. Upon successful consent, the authorization server returns a short-lived code valid for exactly 5 minutes. Exchange this code at POST /oauth2/token to receive an access token (2 hours) and a refresh token (rotating, 90-day expiry). Supported scopes include bot.manage, guild.readonly, analytics.write, and webhook.execute. Always validate the aud claim against api.botnexus.dev before routing requests to your shard workers.
Client Credential Flow
For server-to-server integrations like dashboard sync or webhook ingestion, use the client credentials grant. Submit your application ID and secret to POST /oauth2/token?grant_type=client_credentials. Tokens issued via this method are bound to the originating IP range and carry a strict 500 requests/minute rate limit.
Token Introspection
Verify active sessions without maintaining local state by calling POST /oauth2/introspect. The endpoint returns a JSON payload containing active, exp, scope, and client_id fields. Cache introspection results for 60 seconds to reduce upstream latency during high-traffic guild events.
Revocation & Rotation
Force immediate session termination via POST /oauth2/revoke. When deploying updated bot binaries, trigger token rotation to invalidate stale credentials across all 14 active shard nodes. Automatic rotation is scheduled every 28 days for enterprise-tier applications.
Static Keys, Prefixes, and Access Controls
Complement dynamic OAuth2 sessions with static API keys for legacy service meshes, CI/CD pipelines, and automated deployment hooks.
BotNexus API keys follow the bnx_live_ and bnx_test_ prefix conventions to instantly distinguish production credentials from sandbox environments. Generate keys directly from the Developer Console under Settings > Credentials > API Keys. Each key supports granular permission bindings: bot.deploy, command.register, guild.archive, and billing.read. Keys are hashed using bcrypt (cost factor 12) and never stored in plaintext. Implement key rotation by generating a successor key, updating your environment variables, and revoking the predecessor within a 72-hour overlap window. Monitor usage via the X-Request-Id header and audit logs at GET /v2/keys/audit.
Rate Limits & Throttling
Static keys are subject to tiered rate limits. Basic tier allows 120 requests per minute per key, while Pro tier scales to 2,400 RPM with burst capacity up to 500 concurrent connections. Exceeding limits triggers a 429 Too Many Requests response with a Retry-After header. Implement exponential backoff starting at 500ms.
Environment Isolation
Sandbox keys (bnx_test_) operate against a mirrored guild dataset containing 4,200 synthetic members and 180 channels. All webhook payloads sent from test keys are prefixed with [SANDBOX] and never trigger production moderation actions or billing events.
Header Configuration
Authenticate requests by appending your key to the Authorization: Bearer bnx_live_[KEY] header. Alternatively, use the X-BotNexus-API-Key header for legacy gateway compatibility. Both methods enforce TLS 1.2+ and reject requests missing the Content-Type: application/json declaration.