Authentication and permissions

This page describes how the Management API authenticates callers and which permissions each operation requires. For a first call, see Get started.

Accepted tokens

The Management API accepts two kinds of token:

A User Account Token is issued to a user who signs in to the Mosaic Admin Portal of an environment.
A Service Account Token is issued to a Service Account, which represents a trusted backend integration or script.

Tokens issued to end users through the User Service are rejected. Any other kind of token is rejected as well. Use the End-User API with end-user tokens.

Send the token in the Authorization header of every request.

Authorization: Bearer <token>

The endpoint is:

https://personalization.service.eu.axinom.net/graphql-management

warning

Use User Account Tokens and Service Account Tokens only in trusted tools and backend integrations. Never embed them in applications that end users control.

Get a token

To get a Service Account Token, create a Service Account, grant it permissions, and exchange its credentials for a token. You can also generate a token for testing in the Admin Portal. See Authenticate a Service Account.

A User Account Token is issued by the Identity Service when a user signs in to the Admin Portal of the environment. The permissions in the token come from the roles assigned to that user. See Authentication and Authorization and Identity and Access Management.

Tokens expire. When a token expires, requests fail with the UNAUTHENTICATED code and you must request a new token.

Environment binding

Every token is bound to one tenant and one environment. The Management API reads both from the verified token, and no request argument can change them.

Reads, writes, bulk jobs, and job queries only ever reach data of the token's environment.
A token for one environment cannot be used for another environment. To work with another environment, request a token for that environment.
Bulk job tiers, such as ENVIRONMENT, describe how far a job reaches inside the token's environment, never across environments.
The Personalization Service must be enabled for the environment, otherwise requests fail with UNAUTHENTICATED.

A job id from another environment is treated like an id that does not exist.

Permissions

Each operation requires a permission that the token holds for the Personalization Service. The permission is checked for every operation before it runs. You assign permissions to a role (for User Accounts) or directly to a Service Account in the Admin Portal.

Permission	Admin Portal name	Purpose
`DATA_READ`	Data: Read	Inspect data and look up bulk jobs.
`DATA_WRITE`	Data: Write	Write the data of one named user.
`BULK_DATA_WRITE`	Bulk Data: Write	Submit bulk jobs, look up bulk jobs, and cancel bulk jobs.
`ADMIN`	Admin	Use every Management API operation.

Operation matrix

Operation	Purpose	`DATA_READ`	`DATA_WRITE`	`BULK_DATA_WRITE`	`ADMIN`
`listArrayKeys`	List array keys	Yes	No	No	Yes
`listKeyValueKeys`	List key-value keys	Yes	No	No	Yes
`listArrayItems`	Inspect array items	Yes	No	No	Yes
`listKeyValues`	Inspect key-value entries	Yes	No	No	Yes
`setKeyValue`	Set one user's JSON value	No	Yes	No	Yes
`upsertArrayItem`	Insert or update one array item	No	Yes	No	Yes
`replaceArrayItems`	Replace one user's whole array	No	Yes	No	Yes
`bulkPatchArrayItems`	Submit a bulk patch of array items	No	No	Yes	Yes
`bulkDeleteArrayItems`	Submit a bulk delete of array items	No	No	Yes	Yes
`bulkPatchKeyValues`	Submit a bulk patch of JSON entries	No	No	Yes	Yes
`bulkDeleteKeyValues`	Submit a bulk delete of JSON entries	No	No	Yes	Yes
`bulkJob`	Look up one bulk job	Yes	No	Yes	Yes
`bulkJobs`	List bulk jobs	Yes	No	Yes	Yes
`cancelBulkJob`	Cancel a bulk job	No	No	Yes	Yes

A token needs only one of the permissions marked Yes in a row.

Rules to keep in mind

Grants are not cumulative. DATA_WRITE does not include reads, and BULK_DATA_WRITE does not include listArrayItems or any other data read. A token that writes data and also inspects it needs DATA_READ as well.
Job lookups are shared. DATA_READ and BULK_DATA_WRITE can both look up and list bulk jobs. Only BULK_DATA_WRITE and ADMIN can cancel a job.
Job visibility does not depend on who submitted a job or on its tier. A caller with the right permission sees and can cancel every job of the environment, including jobs that other callers submitted.
Tiers are not authorization boundaries. A permission applies equally to the ENVIRONMENT, APPLICATION, and USER tiers. A token with BULK_DATA_WRITE can submit an ENVIRONMENT tier job. Choosing a narrower tier limits what a job reaches, but it does not limit what the caller is allowed to do.
Dry runs need the same permission as real runs. A dry run is still a bulk job submission.
Progress entries stay read-only. No permission allows you to write, patch, or delete playback progress through the Management API.

Grant the narrowest permission that covers the operations a token needs. Create separate Service Accounts for separate integrations, so that each one can be limited and revoked on its own.

How requests are authorized

The token is verified. Tokens that are missing, expired, invalid, of an unsupported kind, or for an environment that does not use the service fail with UNAUTHENTICATED.
Every root field of the operation is checked against the token's permissions before any of them runs. If any root field is not permitted, the whole operation fails with FORBIDDEN and nothing is executed. This includes fields in fragments and fields that carry @skip or @include.
The operation runs against the environment of the token.

An operation can select at most 10 root fields by default, counting aliases and fragment spreads. See Errors and limits.

Schema introspection fields, such as __schema and __typename, need no permission. A request that contains only introspection fields needs no token where introspection is enabled.

Authorization errors

Code	Meaning	What to do
`UNAUTHENTICATED`	The token is missing, expired, invalid, of an unsupported kind, or not valid for this environment.	Request a new token of a supported kind for the correct environment.
`FORBIDDEN`	The token is valid but holds no permission for an operation in the request.	Grant a permission listed in `requiredPermissions`, then request a new token.

A FORBIDDEN error carries these extensions:

{
  "errors": [
    {
      "message": "The caller is not authorized to use the operation 'listArrayItems'.",
      "extensions": {
        "code": "FORBIDDEN",
        "reason": "USER_NOT_AUTHORIZED",
        "operation": "listArrayItems",
        "requiredPermissions": ["ADMIN", "DATA_READ"]
      }
    }
  ]
}

Extension	Meaning
`reason`	`USER_NOT_AUTHORIZED`.
`operation`	The root field that was not permitted.
`requiredPermissions`	Permissions that allow the operation. Any one of them is enough.

Permissions are part of the token. After you change the permissions of a role or a Service Account, request a new token to receive them. Use extensions.code and extensions.reason to handle these errors, never the message text. UNAUTHENTICATED failures can be returned with an HTTP error status, so inspect the response body as well as the status.

Accepted tokens​

Get a token​

Environment binding​

Permissions​

Operation matrix​

Rules to keep in mind​

How requests are authorized​

Authorization errors​

Related pages​