Skip to main content

​
Introduction

The Osmium Chat Protocol uses a token-based authentication system that supports multiple authentication methods including email/password sign-in, passwordless sign-up, and token-based authorization.

​
Authentication Flow

The authentication system follows a standard request-response pattern:
  1. Initial Authentication: User signs in or signs up
  2. Token Generation: Server returns an authorization token
  3. Session Creation: A session is created and tracked
  4. Subsequent Requests: Client uses the token to authorize future requests

​
Authorization Response

All authentication methods (SignIn, SignUp, and Authorize) return the same Authorization message: 
message Authorization {
  string token = 1;
  tangle.client.types.User user = 2;
  // @snowflake<Session>
  fixed64 session_id = 3;
}
​
token
string
required
The authentication token to use for subsequent API requests
​
user
User
required
The authenticated user object containing profile information
​
session_id
fixed64
required
Unique snowflake identifier for the created session

​
Authentication Methods

The protocol supports three authentication methods:

​
1. Email/Password Sign-In

Traditional authentication using email and password credentials. Method: auth.signIn → auth.Authorization

​
2. Sign-Up

Create a new account with optional email/password or passwordless registration. Method: auth.signUp → auth.Authorization

​
3. Token Authorization

Authenticate using an existing token (e.g., for reconnection or multi-device login). Method: auth.authorize → auth.Authorization

​
Token Management

Authentication tokens should be stored securely on the client and included in all authenticated requests.
Tokens are:
  • Generated server-side during authentication
  • Associated with a specific session
  • Used to identify and authorize the user
  • Can be revoked by ending the associated session

​
Security Features

​
Session Tracking

Each authentication creates a unique session that tracks:
  • Device information (type, version)
  • Application details (name, version)
  • Geographic location (country, region)
  • Last activity timestamp

​
Multi-Device Support

Users can maintain multiple active sessions across different devices. Each session is independently tracked and can be revoked individually.

​
Email Verification

The protocol includes email verification endpoints:
  • auth.verifyEmail: Verify email with a verification code
  • auth.resendEmailVerification: Request a new verification code

​
Password Reset

Secure password reset flow:
  • Request reset with email address
  • Confirm reset with verification code and new password
Method: auth.resetPassword → ()

​
Next Steps

Sign In & Sign Up

Learn about user registration and authentication

Session Management

Manage and revoke user sessions

Invite System

Understand community and chat invites

Build docs developers (and LLMs) love

Get started for freeTalk to us