Authentication

Overview

Fluxer supports multiple authentication methods depending on your use case:

Bot Tokens

Long-lived tokens for bot applications

OAuth2

User authorization for third-party apps

User Sessions

Email/password or SSO authentication

This guide covers all authentication methods and when to use each.

Bot Tokens

Bot tokens are the primary authentication method for programmatic API access. They provide:

Long-lived authentication (doesn’t expire)
Full API access scoped to bot permissions
Simple header-based authentication
No refresh flow required

Creating a Bot Token

Create OAuth2 Application

Navigate to User Settings → Applications
Click New Application
Provide a name and click Create

Copy Bot Token

In the application details, find the Bot section and copy the token.

The token is only shown once. Store it securely immediately.

Use in API Requests

Add the token to the Authorization header:

Authorization: Bot YOUR_BOT_TOKEN

Bot Token Format

Bot tokens in Fluxer are base64-encoded strings containing:

User ID (snowflake)
Creation timestamp
Random entropy
HMAC signature

Bot tokens start with the bot user’s ID. Never share tokens publicly as they grant full access to the bot account.

Authentication Header

curl https://api.fluxer.app/api/v1/users/@me \
  -H "Authorization: Bot YOUR_BOT_TOKEN"

Resetting a Bot Token

If your token is compromised, reset it immediately:

Navigate to Application

Go to User Settings → Applications → Your Application

Reset Token

Click Reset Token in the Bot section

Requires password confirmation (or MFA if enabled). The old token is immediately invalidated.

Update Your Code

Replace the old token with the new one in all deployments

Reset Token API

Programmatically reset tokens via API:

const response = await fetch(
  `https://api.fluxer.app/api/v1/oauth2/applications/${applicationId}/bot/reset-token`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${userToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      password: 'your_password' // Required for sudo mode
    })
  }
);

const { token } = await response.json();
console.log('New bot token:', token);

Token reset requires sudo mode authentication. If MFA is enabled on the owner account, you must provide MFA verification.

OAuth2 Authentication

OAuth2 allows users to authorize your application to access their Fluxer account without sharing passwords.

OAuth2 Flow

Authorization Request

Redirect users to Fluxer’s authorization endpoint:

https://fluxer.app/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=identify%20email

Parameters:

client_id: Your application’s client ID
redirect_uri: Where to send the user after authorization
response_type: Always code
scope: Space-separated scopes (e.g., identify email guilds)

User Authorization

User reviews requested permissions and clicks Authorize

Authorization Code

Fluxer redirects to your redirect_uri with an authorization code:

https://yourapp.com/callback?code=AUTHORIZATION_CODE

Token Exchange

Exchange the code for an access token:

curl -X POST https://api.fluxer.app/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Available Scopes

identify
email
guilds
bot

Scope: identifyAccess basic user information:

User ID
Username and discriminator
Avatar
Bot and system flags

{
  "id": "1234567890",
  "username": "user",
  "discriminator": "0001",
  "avatar": "a_1234567890abcdef",
  "bot": false
}

Scope: emailAccess user’s email address and verification status:

{
  "email": "[email protected]",
  "verified": true
}

Requires identify scope as well

Scope: guildsList guilds the user is a member of:

[
  {
    "id": "1234567890",
    "name": "My Guild",
    "icon": "icon_hash",
    "owner": true,
    "permissions": "2147483647"
  }
]

Scope: botAdd a bot to a guild on behalf of the user. Must specify:

guild_id: Target guild ID
permissions: Requested permission bitfield

scope=bot&guild_id=123456&permissions=2048

Token Exchange

Exchange authorization code for access token:

curl -X POST https://api.fluxer.app/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Token Response

{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "def456...",
  "scope": "identify email"
}

Fields:

access_token: Use for API requests (7 days)
refresh_token: Use to get new access tokens
expires_in: Seconds until access token expires
scope: Granted scopes (may differ from requested)

Using Access Tokens

Authenticate API requests with OAuth2 access tokens:

Authorization: Bearer ACCESS_TOKEN

curl https://api.fluxer.app/api/v1/users/@me \
  -H "Authorization: Bearer ACCESS_TOKEN"

Use Bearer prefix for OAuth2 access tokens, not Bot. Bot tokens use the Bot prefix.

Refreshing Access Tokens

Access tokens expire after 7 days. Use refresh tokens to get new ones:

const params = new URLSearchParams({
  grant_type: 'refresh_token',
  refresh_token: refreshToken,
  client_id: process.env.CLIENT_ID,
  client_secret: process.env.CLIENT_SECRET
});

const response = await fetch('https://api.fluxer.app/api/v1/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: params
});

const newTokens = await response.json();
// Store new access_token and refresh_token

Refresh tokens are single-use. Each refresh returns a new access token AND a new refresh token.

Revoking Tokens

Revoke access or refresh tokens:

await fetch('https://api.fluxer.app/api/v1/oauth2/token/revoke', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    token: accessToken,
    client_id: process.env.CLIENT_ID,
    client_secret: process.env.CLIENT_SECRET
  })
});

User Authentication

User authentication is for direct account access (not third-party apps). Methods include:

Email and Password

Standard login flow:

const response = await fetch('https://api.fluxer.app/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'SecurePassword123!'
  })
});

const result = await response.json();

Handle Response

Response varies based on account settings:Without MFA:

{
  "token": "eyJhbGc...",
  "user_id": "1234567890"
}

With MFA:

{
  "mfa": true,
  "ticket": "mfa_abc123",
  "allowed_methods": ["totp", "sms", "webauthn"],
  "sms_phone_hint": "****1234"
}

Complete MFA (if required)

Submit TOTP code:

await fetch('https://api.fluxer.app/api/v1/auth/login/mfa/totp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    code: '123456',
    ticket: 'mfa_abc123'
  })
});

Multi-Factor Authentication (MFA)

Fluxer supports three MFA methods:

TOTP (Authenticator)
SMS
WebAuthn

Time-based one-time passwords (Google Authenticator, Authy, etc.)Setup:

Generate TOTP secret
Display QR code to user
User scans with authenticator app
Verify with initial code

Login:

await fetch('https://api.fluxer.app/api/v1/auth/login/mfa/totp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    code: '123456',
    ticket: mfaTicket
  })
});

SMS-based verification codesSetup:

Add phone number to account
Verify with SMS code
Enable SMS MFA

Login:

// Request SMS code
await fetch('https://api.fluxer.app/api/v1/auth/login/mfa/sms/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ ticket: mfaTicket })
});

// Verify SMS code
await fetch('https://api.fluxer.app/api/v1/auth/login/mfa/sms', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    code: '123456',
    ticket: mfaTicket
  })
});

Hardware security keys and biometric authenticationSetup:

Request registration options
Create credential with WebAuthn API
Verify and store credential

Login:

// Get authentication options
const options = await fetch(
  'https://api.fluxer.app/api/v1/auth/login/mfa/webauthn/authentication-options',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ticket: mfaTicket })
  }
).then(r => r.json());

// Use WebAuthn API to get credential
const credential = await navigator.credentials.get({
  publicKey: options
});

// Verify credential
await fetch('https://api.fluxer.app/api/v1/auth/login/mfa/webauthn', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    response: credential,
    challenge: options.challenge,
    ticket: mfaTicket
  })
});

SSO (Single Sign-On)

Fluxer supports OAuth2-based SSO with Bluesky:

// Initiate SSO
const { session_url } = await fetch(
  'https://api.fluxer.app/api/v1/auth/sso/start',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ provider: 'bluesky' })
  }
).then(r => r.json());

// Redirect user to session_url
window.location.href = session_url;

// After OAuth callback, complete SSO
const { token, user_id } = await fetch(
  'https://api.fluxer.app/api/v1/auth/sso/complete',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ code: authorizationCode })
  }
).then(r => r.json());

Session Management

User sessions are token-based with the following lifecycle:

Creating Sessions

Sessions are created on:

Successful login
Registration completion
Password reset
OAuth2 authorization

Each session receives a unique token for authentication.

Session Details

Fetch active sessions:

const sessions = await fetch('https://api.fluxer.app/api/v1/auth/sessions', {
  headers: { 'Authorization': `Bearer ${userToken}` }
}).then(r => r.json());

Sessions Response

[
  {
    "id_hash": "abc123...",
    "client_info": {
      "os": "Windows 10",
      "browser": "Chrome 120",
      "device": "Desktop"
    },
    "created_at": "2026-03-01T12:00:00Z",
    "last_used_at": "2026-03-04T10:30:00Z"
  }
]

Logging Out

Revoke specific sessions:

// Logout current session
await fetch('https://api.fluxer.app/api/v1/auth/logout', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${userToken}` }
});

// Logout all sessions
await fetch('https://api.fluxer.app/api/v1/auth/sessions/logout', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${userToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    session_id_hashes: ['hash1', 'hash2'],
    password: 'user_password' // Required for sudo mode
  })
});

Security Best Practices

Store Tokens Securely

Don’t:

Hardcode tokens in source code
Commit tokens to version control
Log tokens in application logs
Send tokens in URL parameters

Do:

Use environment variables
Use secret management services
Encrypt tokens at rest
Rotate tokens periodically

Implement Token Rotation

For OAuth2 applications:

Refresh access tokens before expiry
Store refresh tokens securely
Handle refresh failures gracefully
Invalidate old tokens after rotation

For bot tokens:

Rotate on suspected compromise
Use different tokens per environment
Monitor for unauthorized usage

Validate Scopes

Request minimum required scopes
Validate granted scopes match requested
Handle scope changes gracefully
Document required scopes for users

Monitor Authentication

Log authentication attempts
Track failed login attempts
Alert on suspicious activity
Implement rate limiting

Authentication Comparison

Feature	Bot Tokens	OAuth2 Access Tokens	User Sessions
Lifetime	Permanent	7 days	Until logout
Refresh	Not needed	Refresh token	Re-login
Use Case	Bots & services	Third-party apps	Direct users
Prefix	`Bot`	`Bearer`	`Bearer`
Scopes	Full bot access	User-granted	Full user access
Revocation	Manual reset	Automatic or manual	Logout

Next Steps

Make API Calls

Use your tokens to interact with the Fluxer API

API Reference

Browse all available endpoints

OAuth2 Deep Dive

Advanced OAuth2 flows and patterns

Rate Limits

Understand API rate limiting

Get Started

Core Features

Self-Hosting

Bot Development

WebSocket Gateway

Topics

Resources

​Overview

Bot Tokens

OAuth2

User Sessions

​Bot Tokens

​Creating a Bot Token

​Bot Token Format

​Authentication Header

​Resetting a Bot Token

​Reset Token API

​OAuth2 Authentication

​OAuth2 Flow

​Available Scopes

​Token Exchange

​Using Access Tokens

​Refreshing Access Tokens

​Revoking Tokens

​User Authentication

​Email and Password

​Multi-Factor Authentication (MFA)

​SSO (Single Sign-On)

​Session Management

​Creating Sessions

​Session Details

​Logging Out

​Security Best Practices

​Authentication Comparison

​Next Steps

Make API Calls

API Reference

OAuth2 Deep Dive

Rate Limits

Build docs developers (and LLMs) love

Overview

Bot Tokens

Creating a Bot Token

Bot Token Format

Authentication Header

Resetting a Bot Token

Reset Token API

OAuth2 Authentication

OAuth2 Flow

Available Scopes

Token Exchange

Using Access Tokens

Refreshing Access Tokens

Revoking Tokens

User Authentication

Email and Password

Multi-Factor Authentication (MFA)

SSO (Single Sign-On)

Session Management

Creating Sessions

Session Details

Logging Out

Security Best Practices

Authentication Comparison

Next Steps