auth-service API

Session management and authentication canister. Handles login, token refresh, and device management.

Candid file: auth-service/src/auth_service.did

Types

AuthMethodType

Supported authentication methods:

type AuthMethodType = variant {
  EmailPassword;
  InternetIdentity;
  Google;
  Apple;
  Microsoft;
  GitHub;
  Discord;
};

DeviceTrustLevel

Device trust classification:

type DeviceTrustLevel = variant {
  Trusted;     // Known device with established history
  New;         // First time seeing this device
  Suspicious;  // Anomalies detected (IP change, etc.)
};

UserSession

Complete session record:

type UserSession = record {
  session_id: text;
  user_id: text;
  auth_method: AuthMethodType;
  user_principal: opt principal;

  // Dual-token system
  access_token: text;
  refresh_token: text;
  refresh_count: nat32;
  last_refresh: nat64;

  // Timestamps (nanoseconds)
  created_at: nat64;
  access_expires_at: nat64;
  refresh_expires_at: nat64;
  last_activity: nat64;

  // Device info
  device_fingerprint: text;
  device_first_seen: nat64;
  device_trust: DeviceTrust;

  // Optional security metadata
  ip_hash: opt text;
  last_timezone: opt text;
  user_agent: opt text;
};

LoginResponse

Response from login methods:

type LoginResponse = record {
  success: bool;
  message: text;
  access_token: opt text;
  refresh_token: opt text;
  access_expires_at: opt nat64;
  refresh_expires_at: opt nat64;
  user_id: opt text;
};

Methods

Authentication

login_email_password

Authenticate with email and password.

"login_email_password": (
  email: text,
  password: text,
  device_fingerprint: text,
  ip_address: opt text,
  timezone: opt text,
  user_agent: opt text
) -> (LoginResponse);

TypeScript Example:

const result = await authActor.login_email_password(
  'user@example.com',
  'securePassword123',
  generateDeviceFingerprint(),
  [clientIP],
  [Intl.DateTimeFormat().resolvedOptions().timeZone],
  [navigator.userAgent]
);

if (result.success) {
  localStorage.setItem('access_token', result.access_token[0]);
  localStorage.setItem('refresh_token', result.refresh_token[0]);
}

Session Management

validate_session (query)

Validate an access token and get session info.

"validate_session": (
  access_token: text,
  current_ip_hash: opt text
) -> (variant { Ok: SessionInfo; Err: text }) query;

Returns:

• Ok(SessionInfo) - Valid session with user info
• Err("Session expired") - Token expired
• Err("Invalid token") - Token not found

refresh_tokens

Refresh expired access token using refresh token.

"refresh_tokens": (request: RefreshTokenRequest) -> (RefreshTokenResponse);

Request:

type RefreshTokenRequest = record {
  refresh_token: text;
  device_fingerprint: text;
  ip_address: opt text;
  timezone: opt text;
  user_agent: opt text;
};

Logout

logout

End a single session.

"logout": (session_id: text) -> (variant { Ok; Err: text });

logout_all

End all sessions for a user.

"logout_all": (user_id: text) -> (variant { Ok: nat64; Err: text });

Returns count of sessions terminated.

Password Reset

request_password_reset

Initiate password reset flow.

"request_password_reset": (email: text) -> (variant { Ok; Err: text });

Sends reset link via oracle-bridge email service.

reset_password

Complete password reset with token.

"reset_password": (token: text, new_password: text) -> (variant { Ok; Err: text });

Device Management

get_user_devices (query)

Get all trusted devices for a user.

"get_user_devices": (user_id: text) -> (vec TrustedDevice) query;

trust_device

Mark a device as trusted.

"trust_device": (request: TrustDeviceRequest) -> (variant { Ok; Err: text });

revoke_device_trust

Revoke trust status from a device.

"revoke_device_trust": (user_id: text, device_fingerprint: text) -> (variant { Ok; Err: text });

Configuration (Controller Only)

set_user_service

Set the user-service canister principal.

"set_user_service": (principal) -> (variant { Ok; Err: text });

set_oracle_bridge

Configure oracle-bridge for email sending.

"set_oracle_bridge": (url: text, api_key: text) -> (variant { Ok; Err: text });

Statistics

get_stats (query)

Get session statistics.

"get_stats": () -> (SessionStats) query;

type SessionStats = record {
  total_sessions: nat64;
  active_users: nat64;
};

health (query)

Health check endpoint.

"health": () -> (text) query;

Error Messages

Error	Cause	Resolution
Invalid credentials	Wrong email/password	Check credentials
Session expired	Access token expired	Use refresh_tokens
Refresh token expired	Refresh token expired	User must login again
Device not recognized	New device detected	Complete device verification
Too many login attempts	Rate limiting	Wait before retrying