Immich.API.OAuth (ex_immich v0.1.1)

OAuth authentication flow for the Immich API.

This module provides the two-step authorization code flow used by Immich:

authorize/2 starts the flow and returns a remote login URL.
callback/3 completes the flow after the browser redirect and builds an Immich.API.Session.

The module is intentionally stateless. Callers are responsible for storing the returned OAuth context between steps.

Shared options

Most functions accept shared_opts:

:base_url (required) - Immich server URL (for example "https://demo.immich.app")
:client (optional) - HTTP client module implementing Immich.API.Client.Behaviour (defaults to Immich.API.Client)

Usage

alias Immich.Api.OAuth

opts = [base_url: "https://demo.immich.app"]

# Step 1: Start flow
{:ok, login_url, oauth_context} =
  OAuth.authorize("http://localhost:55555/oauth-callback", opts)

# Open login_url in browser, then receive callback URL in your app.
callback_url = "http://localhost:55555/oauth-callback?code=...&state=..."

# Step 2: Complete flow
{:ok, session} = OAuth.callback(callback_url, oauth_context, opts)

# session.access_token can now be used for authenticated API calls.

Error handling

Functions return {:error, reason} tuples for API-level failures, including transport/authentication errors from the configured client and unexpected successful payloads ({:unexpected_response, payload}).

Summary

Types

base_url()

Immich server base URL without the trailing /api (for example, https://demo.immich.app)

callback_uri()

Callback URI received after OAuth login.

login_url()

oauth_context()

oauth_error()

Error tuple returned by OAuth functions.

redirect_uri()

Redirect URI sent to the authorize endpoint.

shared_opts()

Shared options for OAuth requests.

Functions

authorize(redirect_uri, opts)

Starts OAuth login

callback(callback_url, oauth_context, opts)

Completes OAuth callback exchange and returns an authenticated session.