Users and Access Control

Users

Users are entities that can interact with the Vertex.

They can be created and managed using the Vertex REST API Admin endpoints.

A User is identified by its user_id and has API Keys, which can then be used to authenticate the User while interacting with the Vertex.

It is recommended to use different Users for different machines using the Vertex for different purposes.

Users are classified with respect to their Roles.

Each User is assigned one or more Roles from a preconfigured list of available Roles listed below.

System Roles

Each endpoint exposed by the Vertex is one of two kinds:

1. A public endpoint where no authentication is required (no API Key needed).
2. A private endpoint that can only be called by authorized Users. A User is authorized to access the endpoint only when they provide a valid API key and have the appropriate Role to execute the request.

The following table is a comprehensive listing of all roles in the system:

Role Name	Description
SystemAdmin	Performs all administrative operations (i.e. manage Users and Policies)
PoliciesManager	Manages Policies and Rules (can create, delete, etc.)
ResourceViewer	Views Users, Keys, Policies, Rules, etc.
CryptoUser	Initiates crypto operations (i.e. sign, derive-pubkey)
KeysManager	Can manage key lifecycle (can create, delete, refresh, reshare, etc.)
KeysImporter	Can only import keys
KeysExporter	Can only export keys

For each API endpoint, all Roles that are authorized to call the endpoint are noted in its API Reference page.

Backwards Compatibility

All /admin endpoints remain accessible by the Admin Token set in the Vertex startup configuration in addition to Users with sufficient Roles.

Users & Roles

Every User is created with a set of Roles - the default set is [CryptoUser, KeysManager, KeysImporter, KeysExporter].

A SystemAdmin can add or remove Roles for an existing User. A User with a SystemAdmin or ResourceViewer can always check which Roles are set for a User using /admin/get-user-roles.

A SystemAdmin can also create a User with a custom set of Roles using /admin/create-user-with-custom-roles.

For typical use cases, a sensible configuration may include:

1. One or more SystemAdmin Users for IT / Infra teams.
2. Users with ResourceViewer and PoliciesManager Roles for dev teams.
3. A User with the minimal set of key using Roles (e.g. CryptoUser, KeysImporter, etc.) possible for production machines that perform the actual crypto operations.

Creating a User

To create a User, a SystemAdmin must send a GET request to the /admin/create-user endpoint.

In case a custom set of Roles is required for the User, use the /admin/create-user-with-custom-roles endpoint instead.

The request may include a name query parameter, which is a human-readable, unique name for the User:

curl -L -X GET 'https://<YOUR_VERTEX>/admin/create-user?name=human-readable-name-for-user' \
-H 'Accept: application/json' \
-H 'Authorization: <ADMIN_TOKEN>'

In response, an API key will be generated for the User and returned to the SystemAdmin, together with a user_id that the SystemAdmin may then use for setting Policies for the User or other administrative operations.

Managing User API Keys

• A User can have multiple API Keys, or none at all.
• Every User starts with one API key, which is generated when the User is created.
• An Admin can generate additional API Keys for a User by sending a GET request to the /admin/generate-api-key endpoint.
• An Admin can also revoke an API key by sending a DELETE request to the /admin/revoke-api-key endpoint.
• If a User has no API Keys, the User will not be able to interact with the Vertex but its Keys and data will still be stored by the Vertex and a SystemAdmin will be able to create a new API Key for it to "activate" this User again.

Deleting a User

To delete a User, an Admin must send a DELETE request to the /admin/delete-user endpoint. The delete operation will only succeed if the User has no key shares associated with it. If you are sure you want to delete the User, you should first delete all the Keys associated with the User (using /admin/list-all-user-keys to list them and then delete-key-share to delete them) and then delete the User.

Key Ownership and Permissions

Above we detail the different Roles Users have in the system, now we will explain how different Users can be provided permissions to use Keys.

Key Permissions are introduced to specify which Users have which level of access to a specific Key in the system.

There are two types of Key Permissions:

1. An Admin Key Permission allows the User to perform all available key operations on that specific Key. Users with this permission are known as Key Admins.
2. When a User is assigned the Use Key Permission for a specific key, they can only perform sign and derive-pubkey actions on that key. Users with Use permissions are known as Key Users.

Roles and Key Permission Enforcement

Key Permissions are enforced after User Roles.

This means that when a User calls a specific endpoint (e.g. /sign), first its Roles are checked (e.g. are they a CryptoUser or KeysManager) and then the User's Key Permissions are checked for the specific key that they called the endpoint for (e.g. have they been assigned the Admin or Use permission for this speicific Key).

The User that created a Key is automatically assigned the Admin Key Permission to that Key and can perform any action authorized by its Roles.

A SystemAdmin or a KeysManager with the Admin Key Permission for a specific Key can grant Key Permissions to Users using /admin/keys/grant-usage-permission as well as revoke these using /admin/keys/revoke-usage-permission. It can also see all Key Permissions using /admin/keys/get-usage-permissions.

Key Permissions are particularly useful for separating key management responsibilities.

One User can manage a Key's lifecycle (e.g. perform refreshes and reshares), while another User can only sign transactions with that Key.

As an example, an organization assigns Key Permissions to different sets of Users as follows:

1. An operations team that imports sensitive keys into the system, have the Admin Key Permission for the imported keys.
2. A security team responsible for key refresh operations and access management, are assigned an Admin Key Permission as well for those Keys.
3. Production machines that use these Keys to sign transactions, are assigned with a Use permission on those Keys.