What is the primary way to authenticate with the Revolt API?

The primary way to authenticate with the Revolt API is by using token-based authentication, specifically session tokens for user accounts and bot tokens for automated services.

How do I get a bot token for my Revolt application?

You can get a bot token by logging into your Revolt account, navigating to your user settings, finding the 'Bots' section, and creating a new bot. The token will be displayed upon creation.

Is it safe to hardcode my Revolt tokens in my application?

No, it is not safe to hardcode Revolt tokens. They should be stored securely using environment variables or a secrets management service to prevent unauthorized access if your code is exposed.

What is the difference between a session token and a bot token?

A session token authenticates as a specific Revolt user and represents an active user session. A bot token authenticates as an automated bot account with specific permissions, ideal for programmatic integrations.

How do I include my token in an API request?

You typically include your token in the HTTP header of your request. For Revolt, this often involves custom headers like 'x-bot-token' or 'x-session-token', as specified in the Revolt API reference.

Can I use OAuth 2.0 with Revolt for user authentication?

While Revolt's primary API documentation focuses on direct token usage, session tokens obtained after user login can conceptually fit into an OAuth-like flow. For production applications requiring user delegation, a proper OAuth 2.0 implementation or reliance on bot tokens is generally recommended for security.

How often should I rotate my Revolt bot tokens?

It is a good security practice to rotate your Revolt bot tokens regularly, such as every few months, or immediately if you suspect a token has been compromised. This reduces the risk window for attackers.

Revolt Authentication: API Key & Session Token Methods (2026)

Authentication overview

Revolt's API utilizes token-based authentication to secure access to its services. This approach ensures that only authorized clients, whether they are user accounts or automated bots, can perform actions such as sending messages, managing channels, or retrieving user information. The primary authentication mechanisms are session tokens for human users and bot tokens for programmatic integrations. Each token type is designed for specific use cases and requires different acquisition and management procedures. All authenticated requests typically include the token in the Authorization HTTP header as a Bearer token.

The Revolt API is structured to support various interactions, from simple message posting to complex server management, all secured through these token systems. Developers building integrations or custom clients need to correctly implement token handling to maintain secure and functional applications. The open-source nature of Revolt also allows for self-hosted instances, where authentication mechanisms might be further customized or integrated with existing identity providers, though the core API authentication remains consistent with token usage.

Supported authentication methods

Revolt supports two primary token-based authentication methods for accessing its API:

Session Token (User Token): Used for authenticating as a specific Revolt user. This token represents an active user session and grants access to resources that the user is authorized to access. Session tokens are typically obtained after a user successfully logs into their Revolt account. They are suitable for applications that act on behalf of a user, such as custom clients or user-specific tools.
Bot Token: Used for authenticating as a Revolt bot. Bots are automated accounts designed to interact with the platform programmatically. Bot tokens are generated when a new bot is created within the Revolt ecosystem and provide specific permissions granted to that bot. This method is ideal for automated services, integrations, and server moderation tools that operate independently of a specific user session.

Both token types are sent in the Authorization HTTP header, formatted as Bearer <token>. This is a common practice for OAuth 2.0 Bearer Token usage, as detailed by the IETF RFC 6750 for Bearer Token Usage. Adhering to this standard ensures compatibility and secure transmission of credentials.

Authentication Method Comparison

Method	When to Use	Security Level
Session Token	Applications acting on behalf of a specific user (e.g., custom clients, user scripts).	High (Tied to user session, requires user login).
Bot Token	Automated services, integrations, server bots (e.g., moderation bots, webhook handlers).	High (Tied to specific bot permissions, managed by bot owner).

Getting your credentials

Acquiring the necessary credentials for Revolt API authentication involves different steps depending on whether you need a user session token or a bot token.

Obtaining a Session Token

Session tokens are typically retrieved after a successful user login. For web-based applications, this often involves an OAuth 2.0 flow, though Revolt's primary documentation for direct API usage describes manual retrieval for development and testing. To obtain a session token for a logged-in user:

Log into your Revolt account via the web client or desktop application.
Open your browser's developer tools (usually by pressing F12 or Ctrl+Shift+I).
Navigate to the "Application" or "Storage" tab and look for "Local Storage" or "Session Storage".
Find the entry associated with Revolt (e.g., https://app.revolt.chat) and locate the key that stores the authentication token. This key is often named token or similar.

It is important to note that session tokens are personal and grant full access to your account within the scope of the token's permissions. They should be handled with extreme care and never hardcoded into public applications. For production applications, consider implementing a proper OAuth 2.0 flow or relying on bot tokens for server-side integrations, as recommended by security best practices for Google's OAuth 2.0 implementation guidelines.

Obtaining a Bot Token

Bot tokens are designed for programmatic access and are the preferred method for most integrations and automated services. To create a bot and obtain its token:

Log into your Revolt account.
Navigate to your user settings.
Find the "Bots" section.
Click "Create Bot" and follow the prompts to name your bot and configure its permissions.
Once created, the bot's token will be displayed. Copy this token immediately, as it may not be shown again for security reasons.

Bot tokens are persistent until revoked and should be stored securely. Each bot token has a unique ID and a set of permissions that dictate what actions the bot can perform within servers it has joined. For detailed steps on bot creation and permission management, refer to the official Revolt documentation.

Authenticated request example

Once you have obtained a session token or a bot token, you can use it to make authenticated requests to the Revolt API. The token should be included in the Authorization header of your HTTP request, prefixed with Bearer and a space.

Here's an example using curl to fetch information about the currently authenticated user (using a session token) or bot (using a bot token):

curl -X GET \
  https://api.revolt.chat/users/@me \
  -H "x-bot-token: YOUR_BOT_TOKEN_HERE" # For bot authentication

Or, if authenticating as a user with a session token:

curl -X GET \
  https://api.revolt.chat/users/@me \
  -H "x-session-token: YOUR_SESSION_TOKEN_HERE" # For user session authentication

Note: The Revolt API often uses custom headers like x-bot-token or x-session-token instead of the standard Authorization: Bearer header for specific endpoints or legacy reasons. Always consult the Revolt API reference for the exact header required for each endpoint. The primary documentation indicates that x-bot-token is the standard for bots, while x-session-token is used for user sessions. Ensure you replace YOUR_BOT_TOKEN_HERE or YOUR_SESSION_TOKEN_HERE with your actual token.

Example: Sending a message with a Bot Token

To send a message to a specific channel using a bot token:

curl -X POST \
  https://api.revolt.chat/channels/<CHANNEL_ID>/messages \
  -H "x-bot-token: YOUR_BOT_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Hello from my Revolt bot!" }'

Replace <CHANNEL_ID> with the actual ID of the channel where you want to send the message. This example demonstrates how the token enables the bot to interact with specific resources (a channel) that it has permissions for.

Security best practices

Securing your authentication credentials is paramount when working with the Revolt API. Following these best practices helps prevent unauthorized access and protect your applications and user data:

Never hardcode tokens: Do not embed session tokens or bot tokens directly into your source code, especially for public repositories. Store them in environment variables, secure configuration files, or a secrets management service.
Use environment variables: For local development and deployment, use environment variables to inject tokens into your application. This keeps sensitive data out of your codebase.
Implement secure storage: If your application needs to store tokens persistently, use secure storage mechanisms. For web applications, avoid storing sensitive tokens in client-side local storage; prefer HTTP-only cookies or server-side session management.
Restrict bot permissions: When creating a bot, grant it only the minimum necessary permissions required for its functionality. Overly broad permissions increase the risk if the token is compromised. Regularly review and adjust bot permissions as needed.
Rotate tokens regularly: Periodically revoke old tokens and generate new ones. This practice reduces the window of opportunity for attackers to use compromised credentials. Revolt's bot management interface allows for token regeneration.
Monitor API usage: Keep an eye on your bot's activity logs and API usage patterns. Unusual activity might indicate a compromised token or unauthorized access.
Use HTTPS: Always ensure all communications with the Revolt API are conducted over HTTPS. This encrypts the data in transit, protecting your tokens from eavesdropping. All official Revolt API endpoints enforce HTTPS.
Error handling: Implement robust error handling for authentication failures. Do not expose sensitive error messages that could aid an attacker in probing your system.
Educate users (for session tokens): If your application requires users to provide their session tokens, clearly explain the risks and instruct them on how to obtain and securely provide their tokens.
Understand token revocation: Be aware of how to revoke compromised tokens. For bot tokens, this is done through the Revolt bot settings. For session tokens, logging out of Revolt invalidates the session.

Adhering to these security principles helps maintain the integrity and confidentiality of your Revolt integrations. For broader guidelines on API key security, consult resources like the Cloudflare API Token Best Practices which provide general recommendations applicable to various API ecosystems.