Identity - Complete API Reference
Manage user identity, OAuth provider connections, and device authentication.
Chat Commands
View Identity
/identity Show your identity /identity status Auth status /identity devices List linked devices
OAuth Providers
/identity providers List available providers /identity link google Connect Google account /identity link github Connect GitHub account /identity unlink google Disconnect provider
Device Management
/identity device list List devices /identity device name "Work Laptop" Name this device /identity device revoke <id> Revoke device access /identity device revoke-all Revoke all except current
Trust & Security
/identity trust View trust level /identity sessions Active sessions /identity session logout <id> End session /identity security Security settings
TypeScript API Reference
Create Identity Service
import { createIdentityService } from 'clodds/identity';
const identity = createIdentityService({ // OAuth providers providers: { google: { clientId: process.env.GOOGLE_CLIENT_ID, clientSecret: process.env.GOOGLE_CLIENT_SECRET, }, github: { clientId: process.env.GITHUB_CLIENT_ID, clientSecret: process.env.GITHUB_CLIENT_SECRET, }, },
// Session settings sessionDurationMs: 86400000 * 30, // 30 days deviceTrustDurationMs: 86400000 * 90, // 90 days
// Storage storage: 'sqlite', dbPath: './identity.db', });
Get User Identity
const user = await identity.getUser(userId);
console.log(ID: ${user.id});
console.log(Name: ${user.displayName});
console.log(Email: ${user.email});
console.log(Trust level: ${user.trustLevel});
console.log(Created: ${user.createdAt});
Link OAuth Provider
// Generate OAuth URL const authUrl = identity.getOAuthUrl('google', { redirectUri: 'https://your-domain.com/auth/callback', state: 'random-state-string', scopes: ['email', 'profile'], });
// Handle callback const result = await identity.handleOAuthCallback('google', { code: 'oauth-code-from-callback', state: 'random-state-string', });
console.log(Linked: ${result.provider});
console.log(Email: ${result.email});
List Linked Providers
const providers = await identity.getLinkedProviders(userId);
for (const provider of providers) {
console.log(${provider.name}: ${provider.email});
console.log( Linked: ${provider.linkedAt});
console.log( Last used: ${provider.lastUsed});
}
Unlink Provider
await identity.unlinkProvider(userId, 'google');
Device Management
// List devices const devices = await identity.getDevices(userId);
for (const device of devices) {
console.log(${device.id}: ${device.name || 'Unknown'});
console.log( Type: ${device.type}); // 'desktop' | 'mobile' | 'tablet'
console.log( Browser: ${device.browser});
console.log( OS: ${device.os});
console.log( Last seen: ${device.lastSeen});
console.log( Current: ${device.isCurrent});
}
// Name device await identity.nameDevice(userId, deviceId, 'Work Laptop');
// Revoke device await identity.revokeDevice(userId, deviceId);
// Revoke all except current await identity.revokeAllDevices(userId, { exceptCurrent: true });
Session Management
// List active sessions const sessions = await identity.getSessions(userId);
for (const session of sessions) {
console.log(${session.id}: ${session.device});
console.log( Started: ${session.startedAt});
console.log( Last active: ${session.lastActive});
console.log( IP: ${session.ip});
}
// End session await identity.endSession(sessionId);
// End all sessions await identity.endAllSessions(userId);
Trust Level
// Get trust level
const trust = await identity.getTrustLevel(userId);
console.log(Trust: ${trust}); // 'owner' | 'paired' | 'stranger'
// Set trust level (admin only) await identity.setTrustLevel(userId, 'paired');
Trust Levels
Level Access
owner Full admin access
paired Standard user access
stranger No access (must pair)
OAuth Providers
Provider Scopes
Google email, profile
GitHub user:email
Discord identify, email
Twitter users.read
Device Types
Type Detection
desktop
Windows, macOS, Linux
mobile
iOS, Android
tablet
iPad, Android tablet
unknown
Unrecognized UA
Best Practices
-
Link multiple providers — Backup auth methods
-
Review devices regularly — Revoke unused ones
-
Name your devices — Easier to identify
-
Check sessions — Monitor for suspicious access
-
Use strong auth — OAuth over passwords