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.
| Source | Main use | Resulting access context |
|---|---|---|
| Password or OAuth login | Start a user session | A user with a server session |
| Session token | Continue a signed-in client session | A user and one session |
| API key | Automate API calls | A user and a fixed permission set |
| Shared-link key or slug | Reach a public share | The 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
Shared-link scope
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
Shared-link authentication
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 group | Main responsibility | Typical access boundary |
|---|---|---|
/auth and /oauth | Login, logout, account authentication, OAuth linking, and locked-session state | Public setup or authenticated user |
/sessions | Create and manage the user's sessions | Session owner |
/users | Read and change the current user and selected user views | User permission and account context |
/admin/users and /admin/auth | Manage users and server-wide identity links | Administrator plus admin permission |
/api-keys | Manage automation credentials | Key owner and key permission |
/partners | Create and manage known-user sharing | Partner permission and relationship direction |
/shared-links | Create, manage, authenticate, and scope public shares | Link 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
PATCHmigration must keep the current-user and preference update routes mapped to the same permissions and service actions as theirPUTforms.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A request uses an expired or unknown session token | The API returns an authentication failure and does not reach the controller | Stored session lookup, expiry cleanup, and token invalidation |
| An API key requests a permission outside its grant | The request is rejected even when the user owns the account | Route permission check and isGranted |
| A shared link expires or its owner is no longer valid | The public link cannot authenticate | Link validity check before share access |
| A shared link requests an asset outside its scope | The asset is not returned or changed | Shared-link asset and album access checks |
| A user tries to change their own administrator status or delete their own account | The account change is rejected | User administration service rules |
| A locked asset is requested by a session without recent PIN unlock | The protected asset remains unavailable | Session elevated-permission check |
| An OAuth quota claim is invalid or absent | Registration uses the configured default, while an existing account keeps its current quota | Claim validation and separate registration or login-sync rules |
| An OAuth storage label claim is already used by another user | The existing account keeps its current label | Storage-label uniqueness check before claim synchronization |
Key files
| File | Why to read it |
|---|---|
| server/…/auth.guard.ts | Shows how endpoint declarations become request-level authentication checks. |
| server/…/auth.service.ts | Explains the supported credentials, login paths, session validation, OAuth behavior, claim synchronization, and shared-link validation. |
| server/…/access.ts | Defines the difference between credential permission, resource access, partner access, album roles, and shared-link limits. |
| server/…/auth.controller.ts and server/…/oauth.controller.ts | Show the user and OAuth authentication endpoints. |
| server/…/session.controller.ts and server/…/session.service.ts | Show session creation, management, locking, and invalidation. |
| server/…/user.controller.ts | Shows 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.ts | Show the administrator boundary for user accounts. |
| server/…/api-key.controller.ts and server/…/api-key.service.ts | Show scoped API-key creation and rotation. |
| server/…/partner.controller.ts and server/…/partner.service.ts | Show known-user partner sharing and timeline behavior. |
| server/…/shared-link.controller.ts and server/…/shared-link.service.ts | Show public-share lifecycle, password access, and asset scope. |
| server/…/enum.ts | Defines the route-facing permission and credential names used across the access model. |