Service Accounts

As part of our 1.13.0 release series, we have added two new user account types. These are External Service account and Internal Service account.

The reason for adding these is that Service accounts retain username/password authentication capability even when SSO is enabled and password authentication is disabled for regular users. This allows service accounts to continue functioning for API integrations regardless of SSO configuration.

Account limits and permissions

Internal Service account

Each Catalyst build can have one Internal Service account. It will have full unrestricted permissions equivalent to a Super Admin user. Once created, this account can be used to handle all internal API calls such as creating other user accounts, adding users to user groups, etc.

External Service accounts

Each Catalyst build can have up to 5 External Service accounts. These must be given class or record permissions, as required. External Service accounts can be used for integrations with third party suppliers or for services such as DocuSign webhook handling which update envelope and signing statuses.

Creating service accounts

We currently do not have UI for creating these accounts, but they can be easily achieved via a Post API call in the sequencer.

Set up the API call as follows:

The body of the API call should use the JSON:

{   
  "username": "[email-- doesn't need to be real there will be no activation email]",   
  "account\_type": "service\_external",   
  "first\_name": "[name]",   
  "last\_name": "[surname]",   
  "password": "[password]"  
}

An example is shown below:

Important: you don't have to attach the API call. Simply configure a red API Call actor on any sequence in the instance and, when ready, test it using any record ID. Remember to the delete the actor when you get a positive response which will show the new user ID.

Alternatively, you can use an API client like Postman to make the call and create the user account.

The user will be added to the user list in the normal way and the account type will be shown as Service External or Service Internal as appropriate.

Resetting or changing service account passwords

Neither of these account types can do a password reset from the login page. If for any reason the password needs to be reset, it must be done via a Patch API call. These are the only types of user account which can have a password changed in this way. Only a Super admin user can change the Service account's password. The Service account cannot change its own password.

Endpoint

{{client_url}}/api/users/[userID]

Body

{"password": "[new password]"}

It is worth remembering that if you want to update the password for your Internal Service account, you will need to change your sequencer auth object to reference a different user because the Service account cannot be used to change its own password!

Converting an existing service account

If you have an existing "service" account which you would like to convert to one of these new account types, again a Patch request with the below body will suffice:

{"account\_type": "service\_external"}  or {"account\_type": "service\_internal"}

Useful info

1. The value of the service account password must satisfy currently enforced password complexity requirements.
2. A newly created Service Account is automatically activated. Hence the response to POST /api/users/ contains: "status": "active". An account activation email is never sent.
3. There is never the option against these types of user account to "Resend activation email".

Autologyx Classification: Unrestricted, Public