Skip to content

OAuth2 Grant Types

The OAuth 2.0 specification is an authorization framework that contains a set of methods, or grants, that a client application can use to obtain an access token. Each grant type is designed for a specific use case:

The access token can then be passed to an API endpoint, which checks it to determine validity and authorization scope.

PhotoPrism currently supports practical token-based API access via the token endpoint. The authorization endpoint exists, but the Authorization Code Flow is not usable yet.

Server Endpoints

Resource Endpoint Methods
Authorization /api/v1/oauth/authorize GET
Token /api/v1/oauth/token POST
UserInfo /api/v1/oauth/userinfo GET
Revocation /api/v1/oauth/revoke POST
Registration not implemented
Introspection not implemented
End Session not implemented
Device Authorization not implemented

Clients can query the /.well-known/oauth-authorization-server and /.well-known/openid-configuration endpoints for automatic service discovery:

The token endpoint accepts client_credentials requests and PhotoPrism-specific password and session grants. The authorization and userinfo endpoints are currently placeholders that return 405 Method Not Allowed, and the discovery metadata intentionally advertises only the interoperable parts that are implemented today.

Access Tokens

When clients have a valid access token, e.g. obtained through the POST /api/v1/oauth/token endpoint, they can use a standard Bearer Authorization header to authenticate their requests:

Authorization: Bearer <token>

Submitting the access token with a custom X-Auth-Token header is supported as well:

curl -H "X-Auth-Token: 7dbfa37b5a3db2a9e9dd186479018bfe2e3ce5a71fc2f955" \
http://localhost:2342/api/v1/photos?count=10

Besides using the API endpoints provided for this, you can also generate valid access tokens by running the photoprism auth add command in a terminal.

Learn more ›

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.

Protocol References

Authentication Libraries

Documentation Examples