Overview

In Utila, API users are called Service Accounts.

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

1. Service accounts are created in a vault context. The admins of that vault may
   jointly administer the service account in an organizational manner.
2. 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:

[email protected]

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 RSA key pairs. A service account can have
up to 3 active keys at the same time, and every active key is equivalent — a
valid access token can be minted from any of the account's active private keys.

When creating a service account you must supply at least one RSA public key. The
matching private key is later used to create access tokens for requests to the
Utila API (see Authentication for how to mint a
token).

Each key on a service account has:

• A key name (display name), unique among the account's active keys, so admins
  can tell keys apart.
• A fingerprint — the SHA-256 hash of the public key.
• A creation time and a record of the admin who added it.

Managing Keys

Keys can be added, renamed, and removed at any time from the service account's
settings by a vault admin, subject to the following approval rules:

Adding a key to an existing service account is treated like granting access, so
it requires admin quorum approval (just like the initial role assignment).
Removing a key is immediate, so a leaked or unused credential can be revoked
without delay.

Zero-Downtime Key Rotation

Because multiple keys are valid at the same time, you can rotate a service
account's credentials without any interruption to running integrations:

1. Add the new RSA public key and have the resulting vault action approved.
2. Switch your integration to sign access tokens with the new private key.
   Tokens signed with the old key keep working, so there is no downtime.
3. Once all traffic uses the new key, remove the old key. Removal is immediate.

IP Restrictions

As an extra layer of protection, a service account can be restricted to a fixed
set of source IP addresses. When restricted, the Utila API only accepts the
service account's access tokens from those addresses — a request from any other IP
is rejected during authentication, even if the token itself is valid.

This lets you tie a service account to known infrastructure (for example your CI
runners, backend servers, or a NAT gateway's egress IP), so a leaked private key
alone is not enough to call the API.

Under IP Access Restrictions, choose one of:

• Restrict access to trusted IPs only (recommended) — provide one or more
  Whitelisted IP addresses. Use + Add Another Whitelisted IP to add more
  than one.
• Unrestricted — the service account can be used from any IP address.

Notes on whitelisted IPs:

• Each entry is an individual IP address. Both IPv4 and IPv6 are supported.
• CIDR ranges/subnets are not supported — list each address explicitly.
• Matching is exact: the caller's source IP must equal one of the listed
  addresses.

Configuring the allowlist

You can set IP Access Restrictions when creating the service account, or
change them later from the service account's settings.