Personalization Service
Overview
The Personalization Service stores end-user-specific data shared between applications and devices. Common uses include preferences, profile settings, favorites, watch history, and playback progress.
The service provides two GraphQL interfaces for the same personalization data:
- The End-User API lets applications access data for the authenticated end user.
- The Management API lets trusted backend integrations and administrative tools inspect and modify selected end-user data within an environment.
The service works with the User Service for end-user authentication.
Common use cases
- User preferences and settings
- Profile-specific data
- Favorites and watch lists
- Recently viewed content
- Playback progress
How data is organized
Keys
Keys are strings matching ^[\\w-]+(:[\\w-]+)*$. Colons provide simple namespaces, for example ui:preferences, playback:movie:100, and content:favorites.
Values
Key-value and array values are valid JSON. Each JSON value is limited to 10,240 bytes. Progress values use the separate Progress API and are integers.
Scopes
| Scope | Data owner |
|---|---|
USER | A user |
PROFILE | A user and one of their profiles |
APPLICATION | A user, profile, and application |
The same key can contain different values in different scopes. The End-User API resolves ownership from the authenticated end-user context. The Management API takes the tenant and environment from the caller's token and uses explicit targets or filters to select end-user data. Storage scope is distinct from a Management API bulk operation's tier, which describes the reach of that operation.
Interfaces
| End-User API | Management API | |
|---|---|---|
| Endpoint path | /graphql | /graphql-management |
| Intended callers | End-user applications | Trusted backend integrations and administrative tools |
| Authentication | End-user token issued through the User Service | User Account Token or Service Account Token |
| Data selection | Authenticated end-user context | Explicit targets and filters within the token's tenant and environment |
| Progress data | Read and write | Read-only access to stored progress |
End-User API
Use the End-User API for application features that read or update the authenticated end user's data. It includes the Key-value API, Progress API, and Array API. Start with Overview and authentication.
Management API
Use the Management API to discover keys, inspect data across users, write an individual user's data, or run bulk updates and deletions. Access requires the appropriate operation permissions. Progress is read-only and reflects stored values, which can trail live playback. Start with the Management API overview.
Use User Account Tokens and Service Account Tokens only in trusted tools and backend integrations. Do not embed them in end-user applications.
Choose an API
| Requirement | Guide |
|---|---|
| Store one JSON value for the authenticated end user | Key-value API |
| Store frequently changing integer progress | Progress API |
| Store collections with item identity, ordering, or pagination | Array API |
| Discover keys or inspect selected users' data | Find and inspect data |
| Write data for a specified user | Write an individual user's data |
| Update or delete data across multiple users | Bulk updates and deletions |
Endpoints
| API | Endpoint |
|---|---|
| End-User API | https://personalization.service.eu.axinom.net/graphql |
| Management API | https://personalization.service.eu.axinom.net/graphql-management |
Authentication and authorization
The End-User API requires an end-user token issued through the User Service. The token supplies the tenant, environment, user, profile, and application context used for scope resolution.
The Management API accepts User Account Tokens and Service Account Tokens. The token fixes the tenant and environment, and permissions determine which operations the caller may perform. See Management API authentication and permissions.
Limits
Key-value and array JSON values are limited to 10,240 bytes each. Other limits depend on the interface and operation. See End-User API errors and limits or Management API errors and limits.
Pricing
The service fee follows a tiered model depending on the number of end users whose data is stored. See Mosaic Pricing for more information.