This is a guide on how to create and manage service users (machine users) in Unique’s IAM solution (Zitadel).

Creating a service user

Navigate to your organization’s “Users” section and then select the tab “Service Users”

Open

Service users overview

Click on the “+ New” button to create a new service user and enter the details. Choose a descriptive name for the Service User. We recommend using the same value for User Name and Name here. Description is optional but it might be useful to describe the purpose of the service user. Access Token Type must be set to JWT.

Open

Creation of a new service user

Assigning roles

A service user needs certain permission in order to perform API requests. These permissions are granted to the service user via roles the roles in Zitadel. Depending on its purpose the necessary permissions might differ but usually the role chat.admin.all is required.

To assign a role to a service user, navigate to the “Authorizations” section and click on “+ New”. Then select the project for which you want to give the permission (there is usually only one project).

After you selected the project, all roles that are available will be shown. Select the roles that the service user should get.

Generating client credentials

In case the service user needs to call APIs that require an access token, it needs to have client credentials setup to be able to request an access token. In order to generate client credentials, click on the “Actions” button no the top right of the service user overview and select “Generate Client Secret”.

A client-id and client-secret pair will get generated. Copy it before closing the popup and store it in a secure place. You will not see the client-secret again and would need to generate a new one if you need it again.

Generating personal access token (PAT)

To generate a personal access token for a service user, navigate to the “Personal Access Tokens” section and click on the “+ New” button. You will have the option to define a custom expiration date for the token (which is optional).

When clicking the “Add” button, a personal access token will get generated and displayed for copying. Make sure to copy it and store it in a secure place (you won’t be able to see it again).

Getting a JWT access token

A service user that wants to call Unique backend APIs needs to include a JWT access token in the “Authorization” header of the request. To get an access token the service user’s client credentials are used to make a request to the Zitadel API using basic auth.

The following values are needed for getting an access token:

• baseUrl

  • The base URL of the environment.

• basicAuth

  • Basic auth requires to send the service user’s clientId and clientSecret base64 encoded.

  • Base64 encode the following value and use it in the request made to get a token: <clientId>:<clientSecret> (make sure to include the : between the values)

• projectId

  • The project id of the Zitadel project for which the roles have been granted.

Here is the request for getting an access token using basic auth (Replace the values mentioned above with your own values).

Request

Response

The received JWT access token can be used to call the APIs of the various Unique backend services as the service user that the client credentials belong to.