Management API
What the Management API is for
The Management API is a GraphQL API for trusted backend and administration integrations. It lets those integrations work with Personalization data that belongs to many users, without signing in as each user.
Typical tasks include:
- Discover which keys hold data in an environment.
- Inspect the key-value entries and array items stored for a user, a profile, or an application.
- Write a value, an array item, or a whole array for one named user.
- Patch or delete matching data for many users with a bulk job.
- Monitor or cancel a running bulk job.
Use the Management API from server-side code, scripts, and administration tools. Do not expose Service Account credentials or privileged tokens in end-user applications. Use User Account Tokens for signed-in users of trusted administrative tools. Applications that serve end users keep using the End-User API.
Interfaces
The Management API and the End-User API read and write the same stored data. They differ in who calls them and how much data a single request can reach.
| Question | End-User API | Management API |
|---|---|---|
| Who calls it? | A signed-in end user through a frontend application | A trusted backend or administration integration |
| Which token is used? | A token issued through the User Service | A User Account Token or a Service Account Token |
| Whose data can a call reach? | The authenticated user, profile, and application only | Any user in the environment of the token |
| How is data selected? | Implicitly, from the token | Explicitly, with filters, targets, and bulk job tiers |
| Endpoint path | /graphql | /graphql-management |
Data written through the Management API follows the same rules as data written by an end user. A value written for a user is returned to that user by the End-User API, and data an end user wrote can be inspected through the Management API.
Endpoint
https://personalization.service.eu.axinom.net/graphql-management
Send GraphQL operations as HTTP POST requests with a JSON body and an Authorization: Bearer <token> header.
HTTP batching is not supported, so send one GraphQL operation per request.
A single operation can select only a small number of root fields.
See Errors and limits for the current limits.
Tokens and the environment boundary
The Management API accepts only User Account Tokens and Service Account Tokens. Tokens issued to end users through the User Service are not accepted.
Every token belongs to exactly one tenant and environment. Each operation acts only on the data of that environment, and there is no argument to choose another one. To work with the data of a different environment, request a token for that environment.
Each operation requires a permission that the token holds. Read access, immediate write access, and bulk job access are separate permissions, and a token needs only the ones for the operations it uses. See Authentication and permissions for the full mapping.
How data is addressed
Every record that the Management API returns carries an owner that describes where the record is stored.
| Owner field | Meaning |
|---|---|
userId | The user that owns the record |
profileId | The profile that owns the record; null for USER scope |
applicationId | The application that owns the record; null for USER and PROFILE scope |
scope | USER, PROFILE, or APPLICATION, as described in the overview |
key | The key the record is stored under |
Reads select records with a filter on these fields. Immediate writes name exactly one owner with a target that contains the same fields. Bulk jobs select records with a filter and an explicit tier.
Key-value kinds
Key-value entries have a kind.
| Kind | Meaning |
|---|---|
JSON | Any JSON value written under a key |
PROGRESS | A playback progress value stored as an integer through the Progress API |
Progress is read-only in the Management API. You can inspect progress entries, but no Management API operation writes, patches, or deletes them. A progress value reflects what has been stored so far, so it can trail live playback slightly.
What you can do
| Task | Operations | Guide |
|---|---|---|
| Discover keys | listArrayKeys, listKeyValueKeys | Find and inspect data |
| Inspect entries and items with their owners | listKeyValues, listArrayItems | Find and inspect data |
| Write one user's JSON value, array item, or whole array | setKeyValue, upsertArrayItem, replaceArrayItems | Write user data |
| Patch or delete data of many users | bulkPatchArrayItems, bulkDeleteArrayItems, bulkPatchKeyValues, bulkDeleteKeyValues | Bulk updates and deletions |
| Check on or cancel a bulk job | bulkJob, bulkJobs, cancelBulkJob | Monitor and cancel bulk jobs |
Choose a starting point
- Make your first call with Get started.
- Learn how filters, matches, and patches behave in Filtering, matching, and patching.
- Look up error reasons and limits in Errors and limits.