Skip to main content

​
OAuth2 Resource

OAuth2 allows third-party applications to access Fluxer user data and perform actions on their behalf.

​
Application Object

​
Structure

​
id
Snowflake
required
Unique application identifier
​
name
string
required
Application name (1-100 characters)
​
icon_hash
string | null
Hash of the application’s icon
​
description
string | null
Application description (max 400 characters)
​
owner
User object
User who owns the application
​
owner_id
Snowflake
required
ID of the owner user
​
bot_user_id
Snowflake | null
User ID of the application’s bot (if it has one)
​
bot_public
boolean
default:"true"
Whether the bot can be added by anyone
​
bot_require_code_grant
boolean
default:"false"
Whether the bot requires OAuth2 code grant
​
terms_of_service_url
string | null
URL to terms of service
​
privacy_policy_url
string | null
URL to privacy policy
​
redirect_uris
array of strings
OAuth2 redirect URIs
​
client_secret
string
OAuth2 client secret (only shown to owner)
​
verify_key
string | null
Verification key for interactions
​
version
integer
required
Version for optimistic concurrency control

​
Example Application

{
  "id": "777888999000111222",
  "name": "My Fluxer App",
  "icon_hash": "app_icon_hash",
  "description": "An awesome Fluxer integration",
  "owner": {
    "id": "123456789012345678",
    "username": "developer",
    "discriminator": 1234
  },
  "owner_id": "123456789012345678",
  "bot_user_id": "888999000111222333",
  "bot_public": true,
  "bot_require_code_grant": false,
  "terms_of_service_url": "https://example.com/terms",
  "privacy_policy_url": "https://example.com/privacy",
  "redirect_uris": [
    "https://example.com/oauth/callback"
  ],
  "version": 1
}

​
OAuth2 Scopes

Scopes define what permissions an application requests from users.

​
Authorization Flow

​
1. Authorization Request

Direct users to the authorization URL: 
https://fluxer.chat/oauth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scopes}
​
client_id
Snowflake
required
Your application’s client ID
​
redirect_uri
string
required
One of your registered redirect URIs
​
response_type
string
required
Must be code for authorization code grant
​
scope
string
required
Space-separated list of scopes
​
state
string
CSRF protection token (highly recommended)
​
prompt
string
none or consent - controls consent screen display

​
2. User Authorization

User sees a consent screen and approves or denies the request.

​
3. Callback

Fluxer redirects back to your redirect URI: 
https://example.com/callback?code={auth_code}&state={state}

​
4. Token Exchange

Exchange the authorization code for an access token: 
POST /api/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code&code={auth_code}&redirect_uri={redirect_uri}
Response: 
{
  "access_token": "access_token_here",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "refresh_token_here",
  "scope": "identify email guilds"
}

​
5. Using Access Tokens

Include the access token in API requests: 
GET /api/v1/users/@me
Authorization: Bearer {access_token}

​
Token Types

​
Access Token

​
access_token
string
required
Bearer token for API requests
​
token_type
string
required
Always “Bearer”
​
expires_in
integer
required
Seconds until token expires (typically 7 days)
​
scope
string
required
Space-separated granted scopes

​
Refresh Token

​
refresh_token
string
required
Token for refreshing the access token
Refresh tokens:
  • Do not expire (until revoked)
  • Can only be used once
  • Return a new access token and refresh token

​
Refreshing Tokens

When an access token expires, use the refresh token: 
POST /api/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token&refresh_token={refresh_token}
Response: 
{
  "access_token": "new_access_token",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "new_refresh_token",
  "scope": "identify email guilds"
}

​
Revoking Tokens

Revoke an access token or refresh token: 
POST /api/v1/oauth2/token/revoke
Content-Type: application/x-www-form-urlencoded

token={token}

​
Client Credentials

For bot-only applications, use client credentials grant: 
POST /api/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials&scope=bot

​
Endpoints

​
Create Application

POST /api/v1/applications
Create a new OAuth2 application.
​
name
string
required
Application name (1-100 characters)

​
Get Application

GET /api/v1/applications/{application_id}
Retrieve application information.

​
Get Current Application

GET /api/v1/oauth2/applications/@me
Get the current application (using bot token).

​
Modify Application

PATCH /api/v1/applications/{application_id}
Update application settings.
​
name
string
New name
​
description
string | null
New description
​
icon
string | null
Base64 encoded icon
​
redirect_uris
array of strings
OAuth2 redirect URIs
​
terms_of_service_url
string | null
Terms of service URL
​
privacy_policy_url
string | null
Privacy policy URL

​
Delete Application

DELETE /api/v1/applications/{application_id}
Delete the application and revoke all tokens.

​
Reset Client Secret

POST /api/v1/applications/{application_id}/reset-secret
Generate a new client secret (invalidates the old one).

​
Get Authorized Applications

GET /api/v1/oauth2/authorizations
Get applications the current user has authorized.

​
Revoke Authorization

DELETE /api/v1/oauth2/authorizations/{application_id}
Revoke authorization for an application.

​
Best Practices

  1. Never expose client secrets - Keep them server-side only
  2. Use state parameter - Prevent CSRF attacks
  3. Request minimum scopes - Only ask for what you need
  4. Handle token expiration - Implement refresh token flow
  5. Secure redirect URIs - Use HTTPS and validate URIs
  6. Store tokens securely - Encrypt tokens in your database
  7. Implement token revocation - Allow users to disconnect
  • Users - User data accessible via OAuth2
  • Guilds - Guild information
  • Webhooks - Webhook creation scope

Build docs developers (and LLMs) love

Get started for freeTalk to us