Tokens & Authentication
Nexmod uses several authentication mechanisms for different parts of the platform.
User Authentication
Nexmod uses Clerk for user authentication. Sign in with your email or a social provider. User accounts are synced to Nexmod’s database on creation and update.
Agent Tokens
Agent tokens are long-lived API keys used by the Desktop App and other external clients to connect to Nexmod’s WebSocket servers.
Agent tokens are available on Pro plans and above.
Properties
| Property | Description |
|---|---|
| Name | A label to identify the token |
| Token | The secret value (shown only once on creation) |
| Expires At | Optional expiration date |
| Last Used | When the token was last used for authentication |
| Revoked | Whether the token has been revoked |
Creating a Token
- Navigate to Settings → Tokens in the dashboard
- Click Create Token
- Give it a name and optionally set an expiration
- Copy the token immediately — it won’t be shown again
Revoking a Token
Click Revoke next to any token to immediately invalidate it. Revoked tokens cannot be used to authenticate.
How Tokens Are Used
Agent tokens authenticate WebSocket connections. When connecting, the client provides the token as a query parameter. The server hashes it (SHA-256) and looks up the corresponding token record in the database.
Desktop App Pairing
The Desktop App uses a simplified pairing flow instead of manual token management:
- In the dashboard, go to Settings → Tokens and click Generate Pairing Code
- A short-lived 6-digit code and a deep link (
nexmod://pair?code=...) are created - Enter the code in the Desktop App (or click the deep link)
- The app exchanges the code for an agent token via the
/api/agent-tokens/exchangeendpoint - The app stores the token and connects automatically
Pairing Code Properties
| Property | Description |
|---|---|
| Code | 6-character pairing code |
| Expires At | Short expiration (minutes) |
| Used At | When the code was exchanged for a token |
Session Tokens
For the web dashboard’s real-time features (like live chat preview), short-lived session tokens are created automatically. These expire quickly and are not user-manageable.
Connected Accounts
When you connect Twitch or Discord through the dashboard, Nexmod securely stores OAuth tokens:
| Property | Description |
|---|---|
| Platform | Twitch, Discord, etc. |
| Platform User ID | Your ID on that platform |
| Access Token | Encrypted OAuth access token |
| Refresh Token | Encrypted OAuth refresh token |
| Scopes | Permissions granted to Nexmod |
Tokens are encrypted at rest and automatically refreshed when they expire.
Dashboard Permissions
| Action | Required Permission |
|---|---|
| View tokens | tokens:read — Admin and above |
| Create, revoke tokens | tokens:manage — Admin and above |