Overview

In Utila, API users are called Service Accounts.

There are several key differences between service and user accounts, such as:

Service accounts are created in a vault context. The admins of that vault may jointly administer the service account in an organizational manner.
Unlike regular users, service accounts do not require maintaining a manual login session, which is crucial for automation use cases.

Just like users, service accounts have a virtual email address of the form:

{name}@vault-{vault_id}.utilaserviceaccount.io

Where vault_id is the vault where the service account was created, for example:

automation@vault-56fe1ec45.utilaserviceaccount.io

🛡️
The utilaserviceaccount.io domain is controlled by Utila and can not be used by regular users.

Roles and Permissions

It is important to note that creating a service account in a vault does not automatically give it any permissions within the scope of the host vault.

To give the service account permissions within that vault, you need to additionally assign a role to it.

This is designed so that:

Creating a service account does not require a quorum of administrators, but the role assignment does - effectively splitting the responsibility of service account creation and access approval.
(Future) Allowing cross vault service account access.

Currently the only roles assignable to service accounts are:

Viewer - for read only access
Signer - for transaction flow access (in addition to basic read access).

To create a service account, you must be an admin of the vault.

Authentication

Service account access is controlled by an RSA private key.

When creating a service account, you are required to supply the corresponding RSA public key.

The private key is later used to create access tokens to be used in requests to the Utila API.

🚧
Currently, only one private key is supported per service account and it must be an RSA key - this may change as we want to support more types of keys and also allow multiple keys for zero-downtime key replacement.