Module Immich_auth.Session

Session management for Immich CLI with profile support.

This module provides session persistence for Immich authentication, supporting both JWT tokens and API keys. Sessions are stored in profile-specific directories under ~/.config/immich/profiles/<profile>/session.json.

Directory Structure

~/.config/immich/
  config.json           # Stores current_profile setting
  profiles/
    default/
      session.json      # Session for "default" profile
    home/
      session.json      # Session for "home" profile
    work/
      session.json      # Session for "work" profile

Authentication Methods

Immich supports two authentication methods:

  (* Login with API key *)
  let session = Session.create
    ~server_url:"https://immich.example.com"
    ~auth:(Api_key { key = "xxx"; name = Some "cli" })
    () in
  Session.save fs ~profile:"home" session

Types

type auth_method =
  1. | Jwt of {
    1. access_token : string;
    2. user_id : string;
    3. email : string;
    }
  2. | Api_key of {
    1. key : string;
    2. name : string option;
    }
    (*

    Authentication method. API keys are preferred for CLI use as they don't expire.

    *)
type t

Session data.

val jsont : t Jsont.t

JSON codec for sessions.

Session Construction

val create : server_url:string -> auth:auth_method -> unit -> t

create ~server_url ~auth () creates a new session with the current timestamp.

Session Accessors

val server_url : t -> string

server_url t returns the server URL.

val auth : t -> auth_method

auth t returns the authentication method.

val created_at : t -> string

created_at t returns the creation timestamp (RFC 3339).

Profile Management

val default_profile : string

The default profile name ("default").

val get_current_profile : Eio.Fs.dir_ty Eio.Path.t -> string

get_current_profile fs returns the current profile name. Returns default_profile if no profile has been set.

val set_current_profile : Eio.Fs.dir_ty Eio.Path.t -> string -> unit

set_current_profile fs profile sets the current profile.

val list_profiles : Eio.Fs.dir_ty Eio.Path.t -> string list

list_profiles fs returns all profiles that have sessions. Returns profile names sorted alphabetically.

Directory Paths

base_config_dir fs returns the base config directory (~/.config/immich), creating it if needed.

val config_dir : Eio.Fs.dir_ty Eio.Path.t -> ?profile:string -> unit -> Eio.Fs.dir_ty Eio.Path.t

config_dir fs ?profile () returns the config directory for a profile, creating it if needed.

  • parameter profile

    Profile name (default: current profile)

Session Persistence

val save : Eio.Fs.dir_ty Eio.Path.t -> ?profile:string -> t -> unit

save fs ?profile session saves the session.

  • parameter profile

    Profile name (default: current profile)

val load : Eio.Fs.dir_ty Eio.Path.t -> ?profile:string -> unit -> t option

load fs ?profile () loads a saved session.

  • parameter profile

    Profile name (default: current profile)

val clear : Eio.Fs.dir_ty Eio.Path.t -> ?profile:string -> unit -> unit

clear fs ?profile () removes the saved session.

  • parameter profile

    Profile name (default: current profile)

Session Utilities

val is_jwt_expired : ?leeway:int -> string -> bool

is_jwt_expired ?leeway token returns true if the JWT token is expired.

  • parameter leeway

    Extra time buffer in seconds (default: 60)

val is_expired : ?leeway:int -> t -> bool

is_expired ?leeway session returns true if the session is expired. API key sessions never expire.

  • parameter leeway

    Extra time buffer in seconds for JWT (default: 60)

val pp : t Fmt.t

Pretty-print a session.