Client Authentication¶

In order to grant limited access to API clients, you can use the photoprism auth and photoprism clients subcommands to generate authentication tokens for them. While app passwords are bound to user accounts and can be generated by anyone from the UI, OAuth2 access tokens and client credentials can be used to access the REST API without being bound to an account.

App Passwords¶

All users can generate app-specific passwords for their own use from the web interface by navigating to Settings > Account and then clicking the Apps and Devices button.

Alternatively, running the following command in a terminal will generate a new app-specific password e.g. for the admin account, so that WebDAV-compatible clients can synchronize files even if 2FA is enabled for the account or the account password is changed:

photoprism auth add -n Sync -s "webdav" admin

You will then be shown the generated app password so you can copy it and keep it in a safe place or enter it directly into an app, as you will not be able to see it again:

|-----------------------------|---------------------|
| App Password                | Authorization Scope |
|-----------------------------|---------------------|
| HY8fxO-8hvNqB-43UV4q-1AZ0vu | webdav              |
|-----------------------------|---------------------|

For added security, we recommend setting an expiration date for the app passwords and access tokens you generate. Common scopes for use with app passwords are either "*" for Full Access or "webdav" for WebDAV-compatible file synchronization apps.

App passwords can be used as access tokens in the Bearer Authorization header without first creating a session access token, and to obtain short-lived session access tokens through the POST /api/v1/session endpoint.

Command Options¶

The following flags can be used with the photoprism auth add command (if you omit name or scope, you will be asked to enter them interactively):

Command Flag	Description
`--name CLIENT, -n CLIENT`	CLIENT name to help identify the application
`--scope SCOPES, -s SCOPES`	authorization SCOPES e.g. "metrics" or "photos albums" (`"*"` to allow all)
`--expires LIFETIME, -e LIFETIME`	authentication LIFETIME in seconds, after which access expires (-1 to disable the limit) (default: 31536000)

Authorization Scopes¶

One or more of these scopes can be specified to limit the access to certain API endpoints:

files, folders, shares, photos, videos, favorites, albums, moments, calendar, people, places, labels, config, settings, services, users, sessions, logs, webdav, metrics

Clients authenticated with app passwords are unable to change the account password or manage user accounts, even if you specify all scopes or use the wildcard "*" to allow all.

Access Tokens¶

If you do not specify a username as argument for the photoprism auth add command, a client access token will be generated (the same flags and scopes as above can be used to limit token authorization and lifetime):

|--------------------------------------------------|---------------------|
| Access Token                                     | Authorization Scope |
|--------------------------------------------------|---------------------|
| 7dbfa37b5a3db2a9e9dd186479018bfe2e3ce5a71fc2f955 | files folders       |
|--------------------------------------------------|---------------------|

Generating access tokens is a good choice for developers and other advanced users to connect scripts and external services to the PhotoPrism API, e.g. services that collect metrics or start indexing at regular intervals.

Please note, however, that client access tokens cannot be used to synchronize files via WebDAV, even if the token authorization scope is set to "webdav" or "*", as this requires a registered user account. Access tokens can also not be used as a direct password replacement for apps, since clients are not allowed to use the POST /api/v1/session endpoint, which is required for logging in through the user interface.

Client Credentials¶

If clients support authentication via OAuth2 client credentials, you can use the following terminal commands to generate a client_id and client_secret for them, list registered clients, and delete client credentials that are no longer used:

CLI Command	Description
`photoprism clients ls [search]`	Lists registered client applications
`photoprism clients add [username]`	Registers a new client application
`photoprism clients show [identifier]`	Shows client configuration details
`photoprism clients mod [identifier]`	Updates client application settings
`photoprism clients rm [identifier]`	Deletes the specified client application
`photoprism clients reset --yes`	Removes all registered client applications

For example, running the following in a terminal will generate credentials for Prometheus, with access limited to the metrics endpoint:

photoprism clients add -n Prometheus -s metrics

You will then be shown the generated client_id and client_secret so you can copy them and keep them in a safe place:

|------------------|----------------------------------|
| Client ID        | Client Secret                    |
|------------------|----------------------------------|
| csce0w2joodmirvi | 5VKkBeZLDvojjpE9XzCMXShnrxmxHWvN |
|------------------|----------------------------------|

OAuth2 client credentials cannot be directly used for synchronizing files via WebDAV, as a password replacement for apps, or for logging in to the web interface.

Command Options¶

The following parameters can be used with the photoprism clients add command, e.g. to limit the number of access tokens the client can request:

Command Flag	Description
`--name CLIENT, -n CLIENT`	CLIENT name to help identify the application
`--role ROLE, -r ROLE`	client authorization ROLE (default: "client")
`--scope SCOPES, -s SCOPES`	client authorization SCOPES e.g. "metrics" or "photos albums" (`"*"` to allow all)
`--expires LIFETIME, -e LIFETIME`	access token LIFETIME in seconds, after which a new token must be requested (default: 86400)
`--tokens NUMBER, -t NUMBER`	maximum NUMBER of access tokens that the client can request (-1 to disable the limit) (default: 10)

If you omit the name or scope parameter, you will be asked to enter them interactively. One or more of these scopes can be specified to limit the access to certain API endpoints:

files, folders, shares, photos, videos, favorites, albums, moments, calendar, people, places, labels, config, settings, services, users, sessions, logs, webdav, metrics

When requesting access tokens, clients can further restrict the scope of the tokens by passing the scope parameter to the POST /api/v1/oauth/token endpoint.