Skip to main content

​
Overview

Sessions represent active authenticated connections to the Osmium Chat Protocol. Each authentication creates a new session that tracks device information, location, and activity.

​
Session Object

The Session type contains detailed information about an authenticated connection. 
message Session {
  // @snowflake<Session>
  fixed64 id = 1;
  uint32 client_id = 2;
  string device_type = 3;
  string device_version = 4;
  string app_name = 5;
  string app_version = 6;
  fixed64 last_active = 7;
  optional string country = 8;
  optional string region = 9;
}

​
Fields

​
id
fixed64
required
Unique snowflake identifier for this session
​
client_id
uint32
required
Client application identifier
​
device_type
string
required
Type of device (e.g., “mobile”, “desktop”, “web”)
​
device_version
string
required
Operating system or device version (e.g., “iOS 17.2”, “Windows 11”)
​
app_name
string
required
Name of the application (e.g., “Osmium Mobile”, “Osmium Desktop”)
​
app_version
string
required
Version of the client application (e.g., “1.2.3”)
​
last_active
fixed64
required
Timestamp of last activity in this session (Unix timestamp in milliseconds)
​
country
string
Country where the session was created (optional, e.g., “US”, “CA”)
​
region
string
Region or state where the session was created (optional, e.g., “California”)

​
Get Sessions

Retrieve all active sessions for the authenticated user. Method: auth.getSessions → auth.Sessions

​
Request Message

message GetSessions {}
This request takes no parameters. The user is identified by their authentication token.

​
Response Message

message Sessions {
  repeated Session sessions = 1;
  // @snowflake<Session>
  fixed64 current = 2;
}

​
Response Fields

​
sessions
Session[]
required
Array of all active sessions for the user
​
current
fixed64
required
Snowflake ID of the current session (the one making this request)

​
Example Usage

const response = await client.auth.getSessions({});

console.log(`Total active sessions: ${response.sessions.length}`);
console.log(`Current session ID: ${response.current}`);

response.sessions.forEach(session => {
  console.log(`Session ${session.id}:`);
  console.log(`  Device: ${session.device_type} (${session.device_version})`);
  console.log(`  App: ${session.app_name} v${session.app_version}`);
  console.log(`  Location: ${session.country}, ${session.region}`);
  console.log(`  Last active: ${new Date(Number(session.last_active))}`);
  
  if (session.id === response.current) {
    console.log(`  [CURRENT SESSION]`);
  }
});

​
Revoke Sessions

Terminate one or more active sessions, invalidating their authentication tokens. Method: auth.revokeSessions → ()

​
Request Message

message RevokeSessions {
  // @snowflake<Session>
  repeated fixed64 session_ids = 1;
}

​
Parameters

​
session_ids
fixed64[]
required
Array of session IDs to revoke. Each ID is a snowflake identifier.
Revoking a session immediately invalidates its authentication token. Any requests using that token will fail.

​
Example Usage

// First, get all sessions
const { sessions, current } = await client.auth.getSessions({});

// Find sessions to revoke (e.g., old or suspicious sessions)
const sessionsToRevoke = sessions
  .filter(s => s.id !== current) // Don't revoke current session
  .filter(s => {
    const daysSinceActive = (Date.now() - Number(s.last_active)) / (1000 * 60 * 60 * 24);
    return daysSinceActive > 30; // Revoke sessions inactive for 30+ days
  })
  .map(s => s.id);

if (sessionsToRevoke.length > 0) {
  await client.auth.revokeSessions({ session_ids: sessionsToRevoke });
  console.log(`Revoked ${sessionsToRevoke.length} inactive sessions`);
}

​
Use Cases

​
Security Audit

Regularly review active sessions to detect unauthorized access: 
const { sessions } = await client.auth.getSessions({});

sessions.forEach(session => {
  // Check for suspicious locations or unknown devices
  if (session.country !== "US") {
    console.warn(`⚠️ Session from unexpected location: ${session.country}`);
  }
  
  // Check for old sessions
  const daysSinceActive = (Date.now() - Number(session.last_active)) / (1000 * 60 * 60 * 24);
  if (daysSinceActive > 90) {
    console.warn(`⚠️ Session inactive for ${daysSinceActive.toFixed(0)} days`);
  }
});

​
Multi-Device Management

Allow users to see and manage their connected devices: 
function formatSession(session, isCurrent) {
  return {
    id: session.id,
    displayName: `${session.app_name} on ${session.device_type}`,
    details: `${session.device_version} • ${session.country}`,
    lastActive: new Date(Number(session.last_active)),
    isCurrent
  };
}

const { sessions, current } = await client.auth.getSessions({});
const formattedSessions = sessions.map(s => 
  formatSession(s, s.id === current)
);

// Display in UI for user to review and selectively revoke

​
Automatic Cleanup

Implement automatic session expiration: 
async function cleanupOldSessions(maxInactiveDays = 60) {
  const { sessions, current } = await client.auth.getSessions({});
  const now = Date.now();
  
  const expiredSessions = sessions
    .filter(s => s.id !== current)
    .filter(s => {
      const inactiveDays = (now - Number(s.last_active)) / (1000 * 60 * 60 * 24);
      return inactiveDays > maxInactiveDays;
    })
    .map(s => s.id);
  
  if (expiredSessions.length > 0) {
    await client.auth.revokeSessions({ session_ids: expiredSessions });
    return expiredSessions.length;
  }
  
  return 0;
}

// Run periodically
const revokedCount = await cleanupOldSessions(60);
console.log(`Cleaned up ${revokedCount} expired sessions`);
Session IDs are snowflake identifiers, which encode timestamp information. This can be useful for sorting and analyzing session creation patterns.

Build docs developers (and LLMs) love

Get started for freeTalk to us