Overview The Fluxer API supports multiple authentication methods to secure access to resources. Most endpoints require authentication, while some public endpoints can be accessed without credentials.
Authentication Methods Session-Based Authentication The primary authentication method uses HTTP-only cookies for session management. This is the most secure method for web applications.
Login
Send credentials to the /auth/login endpoint: POST /v1/auth/login Content-Type: application/json { "login" : "[email protected] ", "password" : "your_password" }
Receive Session Cookie
The API sets an HTTP-only cookie named fluxer_session: Set-Cookie: fluxer_session=eyJ...; HttpOnly; Secure; SameSite=Lax
Make Authenticated Requests
Include the cookie in subsequent requests: GET /v1/users/@me Cookie: fluxer_session=eyJ...
OAuth2 Authentication Fluxer supports OAuth2 for third-party integrations and applications.
Authorization Code Flow # Step 1: Redirect user to authorization endpoint GET /v1/oauth2/authorize?client_id=YOUR_CLIENT_ID & redirect_uri = YOUR_REDIRECT_URI & response_type = code & scope = identify+email # Step 2: Exchange code for access token POST /v1/oauth2/token Content-Type: application/x-www-form-urlencoded client_id = YOUR_CLIENT_ID & client_secret = YOUR_CLIENT_SECRET & grant_type = authorization_code & code = AUTHORIZATION_CODE & redirect_uri = YOUR_REDIRECT_URI
Using Access Tokens Include the access token in the Authorization header:
GET /v1/users/@me Authorization: Bearer YOUR_ACCESS_TOKEN
Single Sign-On (SSO) Fluxer supports SSO authentication for enterprise deployments.
Start SSO Session
Check SSO Status
Complete SSO
POST /v1/auth/sso/start Content-Type: application/json { "provider" : "saml", "redirect_uri" : "https://your-app.com/callback" }
WebAuthn / Passkeys Fluxer supports passwordless authentication using WebAuthn (FIDO2) and passkeys.
# Get authentication options POST /v1/auth/webauthn/authenticate/options # Complete authentication POST /v1/auth/webauthn/authenticate Content-Type: application/json { "credential" : {...}, "client_data_json" : "...", "authenticator_data" : "..." }
WebAuthn configuration is controlled by auth.passkeys.rp_name, auth.passkeys.rp_id, and auth.passkeys.additional_allowed_origins in the API config.
Session Cookie HTTP-only session cookie: fluxer_session=<token>
Bearer Token OAuth2 access token: Bearer <access_token>
Internal Service Authentication Internal services authenticate using a shared secret key:
Secret key for internal service-to-service communication
Multi-Factor Authentication (MFA) Fluxer supports multiple MFA methods:
TOTP (Time-based One-Time Password) POST /v1/auth/mfa/totp Content-Type: application/json { "code" : "123456", "ticket" : "mfa_ticket_xyz" }
SMS Verification POST /v1/auth/mfa/sms Content-Type: application/json { "code" : "123456", "ticket" : "mfa_ticket_xyz" }
WebAuthn MFA POST /v1/auth/mfa/webauthn Content-Type: application/json { "credential" : {...}, "ticket" : "mfa_ticket_xyz" }
Sudo Mode Sensitive operations require sudo mode verification. Users must re-authenticate within a short time window.
POST /v1/auth/sudo/verify Content-Type: application/json { "password" : "current_password" }
Sudo mode tokens are valid for 15 minutes and are stored in an HTTP-only cookie: fluxer_sudo_mode
Connection Handoff Fluxer supports secure connection handoff for desktop/mobile apps:
# Step 1: Initiate handoff POST /v1/auth/handoff/initiate # Step 2: Poll for status GET /v1/auth/handoff/:code/status # Step 3: Complete handoff POST /v1/auth/handoff/:code/complete
This allows users to authenticate in a browser and seamlessly transfer the session to a native application.
IP Authorization For enhanced security, Fluxer can require IP authorization for new locations:
# Authorize a new IP POST /v1/auth/authorize-ip Content-Type: application/json { "code" : "ip_auth_code_123" } # Poll authorization status GET /v1/auth/authorize-ip/poll?code=ip_auth_code_123
Security Configuration Authentication behavior is configured via the API config:
auth : { sudoModeSecret : string ; // Secret for sudo mode tokens connectionInitiationSecret : string ; // Secret for connection handoff passkeys : { rpName : string ; // Relying Party name rpId : string ; // Relying Party ID (domain) allowedOrigins : string []; // Additional allowed origins }, vapid : { publicKey : string ; // VAPID public key for push privateKey : string ; // VAPID private key email : string ; // VAPID admin email }, bluesky : { // Bluesky OAuth config clientId : string ; clientSecret : string ; redirectUri : string ; } }
Cookie Configuration Session cookies are configured with security best practices:
cookie : { domain : string ; // Cookie domain secure : boolean ; // Require HTTPS httpOnly : true ; // Prevent JavaScript access sameSite : 'Lax' ; // CSRF protection maxAge : 604800000 ; // 7 days }
Best Practices
Always use HTTPS to protect authentication tokens and session cookies from interception.
For OAuth2 applications, implement token refresh logic to maintain long-lived sessions.
When MFA is required, the API returns a ticket field. Use this ticket to complete MFA verification.
Authentication endpoints have strict rate limits to prevent brute-force attacks. Implement exponential backoff.
Check the /users/@me endpoint to validate session state before sensitive operations.
Logout To end a session:
This invalidates the session token and clears the session cookie.
Logout All Sessions POST /v1/auth/sessions/logout Content-Type: application/json { "session_ids" : [ "session_1" , "session_2"] }
Next Steps
API Endpoints Explore available API endpoints
OAuth Applications Build OAuth2 integrations
