# 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](https://docs.sodot.dev/vertex-api-reference) accessible endpoints.

A User is identified by its unique `user_id` and optionally by `user_name` and can interact with the Vertex using API Keys or a JWT-based authentication method (GCP service accounts, Google accounts and Microsoft Entra ID are supported).

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.

## User Authentication Methods

Vertex supports multiple authentication methods for users:

1. **API Key** (`classic_api_key`) - Authenticate using a Vertex-generated API key placed in the Authorization header of the REST API request.
2. **GCP Workload Identity** (`gcp_service_account`) - Authenticate using a GCP identity token (JWT). The token is obtained from GCP's metadata server for the service account associated with the workload.
3. **Google UI** (`google_ui`) - Authenticate using a Google account identity token (JWT). Requires setting the Google OAuth Client ID via the `VERTEX_GOOGLE_CLIENT_ID` environment variable (or the `--google-client-id` CLI argument).
4. **Entra ID UI** (`entra_id_ui`) - Authenticate using a Microsoft Entra ID identity token (JWT). Requires setting the Entra ID Client ID via the `VERTEX_AZURE_CLIENT_ID` environment variable (or the `--azure-client-id` CLI argument), and optionally the tenant ID via `VERTEX_TENANT_ID`.

The enabled authentication methods are configured at Vertex startup using the `VERTEX_ENABLED_AUTH_METHODS` environment variable (or the `--authentication-methods` CLI argument), as a comma-separated list of the method names above, e.g. `VERTEX_ENABLED_AUTH_METHODS=classic_api_key,google_ui,entra_id_ui`.

When making REST API requests, place either the API key or the identity token in the `Authorization` header. Vertex will validate JWTs and match them to users, or use the API key for classic authentication.

:::info[Security Note]
Identity tokens are valid only for one vertex. Custom fields are used to bind tokens to a specific vertex instance, preventing cross-vertex token usage in the case of multi-vertex deployments (e.g. MPC cluster).
:::

## 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.

:::info[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](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/admin/add-roles-to-user) or [remove](https://docs.sodot.dev/vertex-api-reference/#tag/admin/DELETE/admin/remove-user-roles) 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`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/GET/admin/get-user-roles).

A `SystemAdmin` can also create a User with a custom set of Roles using [`/admin/create-user-with-custom-roles`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/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

<Tabs stateKey="auth-method">
  <Tab title="API Key (Classic)">
    To create a User, a `SystemAdmin` must send a POST request to the [`/admin/create-user`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/admin/create-user) endpoint.

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

    ```bash
    curl -L -X POST '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.
  </Tab>

  <Tab title="GCP Service Account">
    To create a User, a `SystemAdmin` must send a POST request to the [`/admin/create-user`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/admin/create-user) endpoint.

    The fields `authentication_provider` and `email` must be included in the request body to specify that the User will authenticate using a GCP service account.

    1. `authentication_provider` must be set to `gcp` (for Google account users use `google`, for Entra ID users use `azure`).
    2. `email` must be set to the email of the GCP service account that will be used to authenticate the User (e.g. `gcp-service-account@example.iam.gserviceaccount.com`).

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

    ```bash
    curl -v -L -X POST 'https://<YOUR_VERTEX>/admin/create-user?name=human-readable-name-for-user' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: <ADMIN_TOKEN>' \
      -d '{"authentication_provider" : "gcp", "email" : "gcp-service-account@example.iam.gserviceaccount.com"}'
    ```

    In response the unique `user_id` of the user will be returned.

    After user creation any request made by the user will happen through identity token issued by GCP.

    **Fetching the GCP Identity Token:**

    For example, from a GCP VM, you can obtain the identity token using the following command:

    ```bash
    gcloud auth print-identity-token --audiences=<vertex_persistent_keygen_id>
    ```

    :::note[Token Audience]
    In order to ensure the identity token is valid for the specific Vertex instance, make sure to set the `--audiences` flag to the [Vertex persistent keygen id](https://docs.sodot.dev/vertex-api-reference/#tag/keygenid/GET/cluster/persistent-keygen-id).
    :::
  </Tab>
</Tabs>

### Managing User API Keys

:::info[Note]
This section is referring to Users which use API keys as authentication methods.
An API key operation on a User which has authentication based on a workload identity will result in an error.
:::

* 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`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/GET/admin/generate-api-key) endpoint.
* An Admin can also revoke an API key by sending a `DELETE` request to the [`/admin/revoke-api-key`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/DELETE/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`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/DELETE/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`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/GET/admin/list-all-user-keys) to list them and then [`delete-key-share`](https://docs.sodot.dev/vertex-api-reference/#tag/ecdsa/DELETE/ecdsa/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 specific Key).

<br />

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`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/POST/admin/keys/grant-usage-permission) as well as revoke these using [`/admin/keys/revoke-usage-permission`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/DELETE/admin/keys/revoke-usage-permission). It can also see all Key Permissions using [`/admin/keys/get-usage-permissions`](https://docs.sodot.dev/vertex-api-reference/#tag/admin/GET/admin/keys/get-usage-permissions).

Roles and Key Permissions can also be assigned to whole [Groups](/vertex/groups) of Users instead of to each User individually.

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.