Introducing a new way to review your PRs.

Read the announcement

immich-app / immich

High performance self-hosted photo and video management solution.

View on GitHub

21 documents · Updated Oct 19, 2026

docs / identity-access-and-sharing

Identity, access, and sharing

Identity and access controls decide who can use the server API, which resources they can reach, and how an owner can share media with another person or with a public link. The system combines password or OAuth login, server-side sessions, scoped API keys, user roles, resource permissions, partner sharing, and shared-link rules before a request reaches a protected operation. See Server API and application runtime for the wider request path and Web administration and authentication for the web-facing administration view.

Access control model

The access model separates identity from resource access. Authentication first resolves a user or a share, then the route and the resource checks decide whether that identity may perform the requested action.

Authentication sources

The server accepts four main authentication sources. A request can carry a shared-link key or slug, a user session token, or an API key. The server gives shared-link credentials priority, so a public share is handled as a share identity rather than as the browser user's identity.

SourceMain useResulting access context
Password or OAuth loginStart a user sessionA user with a server session
Session tokenContinue a signed-in client sessionA user and one session
API keyAutomate API callsA user and a fixed permission set
Shared-link key or slugReach a public shareThe share owner and one shared link

The same identity object carries the user and, when present, the session, API key, or shared link. This lets downstream checks apply both account rules and the limits of the credential used for the request.

References: server/…/auth.service.ts• L224-276 server/…/auth.dto.ts• L15-20

Route enforcement

Protected endpoints declare their access needs with an authentication rule. The rule can mark an endpoint as public, require setup mode, require an administrator, accept a shared link, or attach a named permission. The request guard resolves the credential and rejects an invalid identity before the controller runs.

Resource checks add a second boundary. They test ownership, album membership, partner access, shared-link scope, or the elevated state of a session. This prevents a valid user or API key from using a broad route to reach a resource outside its grant.

flowchart LR
    R[API request] --> C[Resolve credential]
    C --> I[Build identity context]
    I --> G[Check route role and key permissions]
    G --> A[Check resource access]
    A --> O[Run protected operation]

References: server/…/auth.guard.ts• L18-56 server/…/auth.guard.ts• L89-123 server/…/access.ts• L37-56

Authentication and sessions

Authentication turns a password or an external identity into a server session. Sessions let web, mobile, and API clients keep separate access records and let users remove access from one device or from all other devices.

Login paths

Password login checks the account password and creates a session token. OAuth login starts an external authorization flow, validates its state and code verifier, then finds or creates the matching local user according to the OAuth settings. OAuth may also link to or unlink from an existing account.

Both paths return an access token and user summary. The web client also receives cookies that identify the access method. OAuth logout can use the provider's end-session endpoint, and provider back-channel logout can invalidate sessions linked to an external identity.

On each later OAuth login, configured identity claims can refresh an existing user's storage quota or storage label. A valid quota claim changes the quota, while -1 means unlimited storage. A missing claim leaves the current value unchanged. The default username claim is used for registration but does not overwrite an existing storage label unless an explicit label claim is configured. A valid custom storage-label claim is cleaned before the server applies it, and an existing label is not replaced when another user already owns it.

References: server/…/auth.controller.ts• L30-51 server/…/oauth.controller.ts• L40-90 server/…/auth.service.ts• L60-77 server/…/auth.service.ts• L298-381 server/…/auth.service.ts• L643-715 server/…/auth.service.spec.ts• L1207-1402

Session lifecycle

Each login creates a stored session with device details and optional expiry. A client can create a child session for casting, list its sessions, update session state, lock one session, or delete one or all sessions. Password changes can also invalidate other sessions.

The session token is only returned when the session is created. Later requests resolve it to the stored session, refresh client details when they change, and reject an expired or unknown token. A background cleanup removes expired sessions.

sequenceDiagram
    participant Client
    participant Auth as Authentication API
    participant Store as Session store
    participant Resource as Protected API

    Client->>Auth: Login or create session
    Auth->>Store: Save token record
    Auth-->>Client: Return token once
    Client->>Resource: Send session token
    Resource->>Store: Resolve token
    Store-->>Resource: User and session state
    Resource-->>Client: Allow or reject request

References: server/…/session.controller.ts• L21-108 server/…/session.service.ts• L30-87 server/…/auth.service.ts• L550-592

Locked asset sessions

A user PIN protects assets marked as locked without forcing a full account logout. A session starts without elevated access, and a correct PIN grants elevated access for a limited period. The user can lock the session again, while resetting the PIN locks all sessions for that user.

The elevated flag is part of the session access context. Asset and file checks use it when deciding whether the current session may read or change locked content.

References: server/…/auth.controller.ts• L123-180 server/…/auth.service.ts• L152-200 server/…/auth.service.ts• L594-613 server/…/access.ts• L116-149

Users and administration

Users are the local identities that own media and account settings. The server exposes self-service endpoints for the current user and separate administrator endpoints for account management.

User accounts

The current-user API supports profile data, preferences, onboarding state, profile images, and account license data. A user can change account details and password subject to the relevant permission. The server also tracks account status, storage quota and use, OAuth linkage, and whether the account must change its password.

The current-user and preference update contracts support the v3 PATCH migration while retaining the established PUT operations. This lets clients move to the newer update form without changing the account capability that the endpoint protects.

User discovery is limited by account context. Administrators can search all users, while ordinary users see only the set allowed by the server's public-user setting. User deletion first moves an account to a deleted or removing state and can later trigger cleanup of its media and records.

References: server/…/user.controller.ts• L44-136 server/…/user.service.ts• L29-49 server/…/user.service.ts• L254-296 server/…/user.dto.ts• L119-160

Administrator operations

Administrator routes manage accounts across the server. They can create, inspect, update, delete, restore, and review sessions or statistics for a user. The route requires both administrator status and an administrator permission, so an API credential cannot gain administrator access by naming an admin permission alone.

The first administrator is created during setup. A separate administrator action can unlink all OAuth accounts when the server must remove external identity links at once.

References: server/…/user-admin.controller.ts• L26-197 server/…/auth.controller.ts• L53-62 server/…/auth-admin.controller.ts• L13-23 server/…/user-admin.service.ts• L33-125

API keys and permissions

API keys provide non-interactive access for tools and integrations. Each key belongs to one user and carries a set of named permissions that limits what the key can do.

API key lifecycle

An authenticated user can create, list, inspect, update, rotate, and delete their own keys. The secret is returned at creation or rotation time and is not part of later key responses. Rotation replaces the old secret immediately.

When an API key creates or changes another key, it cannot grant permissions that it does not already have. This prevents a limited automation key from creating a more powerful key. Requests authenticated by a key must also satisfy the permission named by the route.

References: server/…/api-key.controller.ts• L16-113 server/…/api-key.service.ts• L12-75 server/…/api-key.dto.ts• L9-39

Permission grants

A permission is a named capability such as reading an asset, sharing an album, managing a session, or administering users. The special all grant covers every named permission. Otherwise, the current grant must contain every permission requested by the operation.

Permissions do not replace ownership checks. For example, an asset-share permission still needs access to the asset through ownership or partner sharing, and an album-share permission still needs ownership or an editor-level album role. This keeps credential scope and resource scope separate.

References: server/…/enum.ts• L112-135 server/…/enum.ts• L225-331 server/…/access.ts• L8-19 server/…/access.ts• L116-227

Sharing relationships

The server supports sharing between known users and sharing through links for people who do not have a server account. Both paths use the same access checks for the media operation, but they differ in how the recipient proves identity.

Partner sharing

A partner relationship lets one user share assets with another user. The sender creates or removes the relationship, and the receiving user can choose whether partner assets appear in the timeline. Partner access contributes to read, view, download, and share checks where the resource rules allow it.

The relationship has a direction. One side is the user who shares, and the other side is the user who receives. The API returns the other user in the requested direction so clients can present a useful partner list.

References: server/…/partner.controller.ts• L16-74 server/…/partner.service.ts• L12-61 server/…/partner.dto.ts• L8-29 server/…/access.ts• L116-145

A shared link exposes either an album or a selected set of individual assets. The owner sets its description, optional custom slug, expiry, password, upload and download rules, and metadata visibility. Individual links can add or remove assets after creation, while album links follow the album's contents.

Creating a link requires share access to the album or asset set. The owner can later list, edit, or delete the link. A link can therefore be narrower than the owner's account access and can expire without changing the owner's media or account.

References: server/…/shared-link.controller.ts• L58-180 server/…/shared-link.service.ts• L69-143 server/…/shared-link.dto.ts• L21-95

A link is identified by a secret key or a public slug. The server checks that the link belongs to a live owner and has not expired. If the link has a password, the visitor must complete the link login flow before protected share operations can use it; the resulting link token is kept in a share-token cookie.

Share requests are restricted to routes marked for shared-link use. Resource checks then apply the link's asset or album scope and its upload, download, and metadata rules. A shared-link identity cannot use an unrelated user route.

References: server/…/auth.service.ts• L500-539 server/…/shared-link.controller.ts• L69-100 server/…/shared-link.service.ts• L27-62 server/…/access.ts• L53-97

Server endpoint groups

The API surface groups access-related operations by the identity or sharing task they serve. The controllers define the public contract, while the authentication guard and access service enforce the common rules used by those controllers.

Endpoint responsibilities

Endpoint groupMain responsibilityTypical access boundary
/auth and /oauthLogin, logout, account authentication, OAuth linking, and locked-session statePublic setup or authenticated user
/sessionsCreate and manage the user's sessionsSession owner
/usersRead and change the current user and selected user viewsUser permission and account context
/admin/users and /admin/authManage users and server-wide identity linksAdministrator plus admin permission
/api-keysManage automation credentialsKey owner and key permission
/partnersCreate and manage known-user sharingPartner permission and relationship direction
/shared-linksCreate, manage, authenticate, and scope public sharesLink owner or shared-link identity

These groups connect to the asset and album APIs. A sharing endpoint may create the grant, but the asset or album endpoint still checks whether the caller may read, upload, download, or change the selected content. See Asset lifecycle and media processing for the downstream media path.

References: server/…/auth.controller.ts• L25-180 server/…/session.controller.ts• L16-108 server/…/user.controller.ts• L44-249 server/…/user-admin.controller.ts• L21-197 server/…/api-key.controller.ts• L11-113 server/…/partner.controller.ts• L11-74 server/…/shared-link.controller.ts• L50-180

Change checklist

When these files or sections are changed, remember to consider these:

  • A new protected endpoint must declare its route role and permission so the request guard, API description, and key checks stay aligned.
  • A new credential source must update the authentication resolution order and the identity context used by resource access checks.
  • A new shared-link capability must update both link settings and the shared-link branches in server/…/access.ts; changing only link creation can leave the operation open or unusable.
  • Changes to user deletion or restore must preserve the relationship cleanup for albums, sessions, partner links, shared links, and media records.
  • Changes to permission names must update route declarations, API-key grants, and any resource access mapping that interprets the permission.
  • Changes to OAuth claim names or value rules must keep registration defaults, later-login synchronization, storage-label uniqueness, and quota-usage updates aligned.
  • Changes to the v3 PATCH migration must keep the current-user and preference update routes mapped to the same permissions and service actions as their PUT forms.

Important failure modes

TriggerConsequenceGuard
A request uses an expired or unknown session tokenThe API returns an authentication failure and does not reach the controllerStored session lookup, expiry cleanup, and token invalidation
An API key requests a permission outside its grantThe request is rejected even when the user owns the accountRoute permission check and isGranted
A shared link expires or its owner is no longer validThe public link cannot authenticateLink validity check before share access
A shared link requests an asset outside its scopeThe asset is not returned or changedShared-link asset and album access checks
A user tries to change their own administrator status or delete their own accountThe account change is rejectedUser administration service rules
A locked asset is requested by a session without recent PIN unlockThe protected asset remains unavailableSession elevated-permission check
An OAuth quota claim is invalid or absentRegistration uses the configured default, while an existing account keeps its current quotaClaim validation and separate registration or login-sync rules
An OAuth storage label claim is already used by another userThe existing account keeps its current labelStorage-label uniqueness check before claim synchronization

Key files

FileWhy to read it
server/…/auth.guard.tsShows how endpoint declarations become request-level authentication checks.
server/…/auth.service.tsExplains the supported credentials, login paths, session validation, OAuth behavior, claim synchronization, and shared-link validation.
server/…/access.tsDefines the difference between credential permission, resource access, partner access, album roles, and shared-link limits.
server/…/auth.controller.ts and server/…/oauth.controller.tsShow the user and OAuth authentication endpoints.
server/…/session.controller.ts and server/…/session.service.tsShow session creation, management, locking, and invalidation.
server/…/user.controller.tsShows current-user, preference, profile-image, license, and onboarding access contracts, including the PUT to PATCH migration.
server/…/user-admin.controller.ts and server/…/user-admin.service.tsShow the administrator boundary for user accounts.
server/…/api-key.controller.ts and server/…/api-key.service.tsShow scoped API-key creation and rotation.
server/…/partner.controller.ts and server/…/partner.service.tsShow known-user partner sharing and timeline behavior.
server/…/shared-link.controller.ts and server/…/shared-link.service.tsShow public-share lifecycle, password access, and asset scope.
server/…/enum.tsDefines the route-facing permission and credential names used across the access model.