Feedback

Summary

The current Immich integration documentation lacks information about required API key permissions, which can lead to user confusion when the media source functionality doesn't work with restrictive API keys.

The problem

Users creating API keys with minimal permissions may find that:

• Core monitoring sensors work fine (disk usage, server info)
• Media source integration fails silently or with unclear errors
• No guidance exists on what permissions are actually required

Proposed Solution

Add a brief section to the Prerequisites explaining the minimal API key permission requirements:

Current Prerequisites section:

## Prerequisites

You need to [obtain the API key](https://immich.app/docs/features/command-line-interface#obtain-the-api-key) for your user account in your Immich instance.

Proposed addition:

## Prerequisites

You need to [obtain the API key](https://immich.app/docs/features/command-line-interface#obtain-the-api-key) for your user account in your Immich instance.

### API key permissions

For full functionality, enable the `album.read` permission when creating your API key. Without this permission, the media source integration will not work, but all monitoring sensors will continue to function normally.

URL

https://www.home-assistant.io/integrations/immich/

Version

2025.6.3

Additional information

Technical Details

Through testing, I've confirmed that the Immich integration uses these API endpoints:

Core functionality (no special permissions required):

• GET /api/users/me - User verification
• GET /api/server/about - Server info
• GET /api/server/storage - Storage statistics
• GET /api/server/statistics - Photo/video counts
• GET /api/server/version-check - Update check

Media source functionality (requires album.read permission):

• GET /api/albums - List albums
• GET /api/albums/{id} - Album details with assets
• GET /api/assets/{id}/thumbnail - Asset thumbnails/images
• GET /api/assets/{id}/video/playback - Video streaming

Benefits

• Reduces user confusion about permission requirements
• Provides clear guidance for minimal security setups
• Explains which features require which permissions
• Maintains the existing documentation style and brevity