Mosaic products documentation: Concepts, API Reference, Technical articles, How-to, Downloads and tools

Authenticate Service Account

What is a Service Account?

Software components interacting with Mosaic Services use Service Accounts. A Service Account is similar to a User Account, but to authenticate it you will use an ID and a Secret (both are long random numbers) against Mosaic Identity Service and not any Identity Provider. Service Accounts can be assigned permissions (same permissions as regular users get). However, it is not possible to assign a Role to a Service Account.

It is recommended to create a separate Service Account for every integration purpose and grant them only those permissions that they really need (least privilege principle).

See also:

How to create a Service Account?

You use the Mosaic Admin Portal to create and manage Service Accounts.

  1. Go to your Environment and select "Service Accounts"

  2. Click "New" to add a new Service Account

  3. Give a name to your Service Account and proceed

    1. Client ID & a randomly generated Client Secret will visible on the screen upon creation, and allow the possibility to copy it to the clipboard.

      New Service Account
      Figure 1. New Service Account in the Mosaic Admin Portal
      Store the secret securely, as you will never see it in the Admin Portal again (only its hash is stored, hence it is impossible to recover it). You can reset the secret anytime to a new value.
  4. Grant permissions to the Service account by clicking "Permissions"

    Service Account Properties
    Figure 2. Service Account Properties in the Mosaic Admin Portal
Use the Client Secret action to re-generate the Service Account secret if needed.

How to Authenticate a Service Account …​

Mosaic Identity Service provides a GraphQL API endpoint to authenticate Service Accounts. You have to provide the Client ID and Client Secret, and you will get in exchange a JWT, that you can use to access any Mosaic services.

The lifetime of this JWT is by default 1 hour, but you can configure it per Environment in the Mosaic Admin Portal under Service Configuration > Identity Service. The setting applies to all Service Accounts of the given Environment.

…​ using GUI?

If you just need a JWT for test purpose, you can generate it in the Mosaic Admin Portal on the page Service Account Properties by clicking "Generate Access Token".

Generate Service Account Access Token
Figure 3. Generate Service Account Access Token in the Mosaic Admin Portal

…​ using API?

Send the following GraphQL mutation to

mutation GetServiceAccountToken {
    input: {
      clientId: "YOUR_CLIENT_ID"
      clientSecret: "YOUR_CLIENT_SECRET"
  ) {

…​ using Mosaic Libraries?

If you develop your own service using TypeScript, you can use a wrapper for the above call implemented in the library @axinom/mosaic-id-link-be:

import { getServiceAccountToken } from '@axinom/mosaic-id-link-be'

Call the method getServiceAccountToken providing

The Response will be an object of TokenResult containing the following properties:

  • accessToken

  • expiresInSeconds

  • tokenType