# Machine Users & Agents

Machine Users & Agents are non-interactive vault identities for any system that calls the vault programmatically: trading bots, back-office automation, and AI agents. They carry the same enterprise-grade controls as human users: deny-by-default Administrative Policy, Signing Policy enforcement, freeze capability, and a full audit trail. Every action an agent takes is attributed to it specifically, not to a shared credential.

![Users and Trading Machines list showing machine users and an AI agent](/img/guide/users-groups/machines.png)
*Machines and agents appear in the same list as human users, tagged Machine in the Type column.*

:::note
The web UI labels these identities **Trading Machines**: they live on the **Users and Trading Machines** tab, and you add one with **Create Trading Machine**. This guide says "machine users and agents" for the concept and uses the UI's **Trading Machine** wording for the controls you click.
:::

## Why agents deserve a first-class identity

When you deploy an AI agent to manage trading or operations on your behalf, you are delegating real financial authority. The vault treats agents the same way it treats any other identity:

* **Policy-gated:** the agent can only perform the actions its groups are permitted to perform. An agent assigned to a read-only group cannot initiate signing, regardless of what the agent software requests.
* **Signing Policy enforced:** signing requests from an agent pass through the same ordered rule evaluation as any other request. You can write rules that permit an agent to sign withdrawals up to a threshold but deny anything above it.
* **Freezeable instantly:** if an agent behaves unexpectedly, you can freeze it from the web UI in seconds. A frozen machine user's signing requests are rejected by the vault.
* **Fully audited:** every signing request and administrative action the agent initiates appears in the audit log attributed to that agent's identity.

## Create a machine user or agent

You need the **Manage Users** capability to create machine users.

1. Navigate to **Users & Groups** in the sidebar.
2. Click **Create New** in the top-right corner and select **Create Trading Machine** from the dropdown.

3) The **Create Trading Machine** modal opens. Enter:
   * **Name** (required): a unique identifier for this machine user or agent. Use a descriptive name that reflects the system or agent (for example, `binance-withdrawal-agent` or `risk-monitor-bot`).
   * **Ed25519 public key** (required): paste the PEM-encoded Ed25519 public key for this identity. The vault uses this key to verify that API requests come from the legitimate holder of the corresponding private key. Generate the key pair outside the vault and provide only the public key here.
   * **Description** (optional): notes about the system's purpose and owner.
4) Click **Submit**.

![Create Trading Machine dialog with a name and a pasted Ed25519 public key in PEM format](/img/guide/users-groups/create-machine-modal.png)
*The operator generates an Ed25519 keypair locally and registers only the public key. The private key never leaves their control.*

## Copy credentials immediately

After creation, the vault displays the machine's API key exactly once. The API key is an identifier, not a secret: the machine proves who it is by signing each request with its own Ed25519 private key (the key you generated and never shared with the vault).

![One-time credential reveal showing the machine API key, with the value redacted](/img/guide/users-groups/credential-reveal.png)
*The API key is shown once and never again. There is no separate secret to store: the machine authenticates by signing each request with its Ed25519 private key, so the API key is only an identifier. (The key value is redacted here.)*

:::warning\[One-time reveal]
Copy the API key before closing this modal. The vault does not store it in retrievable form; once you close this dialog, the API key cannot be shown again. If you lose it, rotate the API key to generate a new one.
:::

Store the API key, together with the machine's Ed25519 private key, in your secrets manager (HashiCorp Vault, AWS Secrets Manager, or equivalent) before proceeding.

## How machine users and agents authenticate

Machine users and agents authenticate API calls using two mechanisms working together:

* **API key**: included in every request as a header. This identifies which machine user is making the request.
* **Ed25519 assertion**: for state-changing requests, the machine user signs a canonical request transcript with its Ed25519 private key. The vault verifies the signature against the registered public key. This ensures that possessing only the API key is not sufficient to modify vault state.

See [Machine Users & Agents (Ed25519)](/develop/authentication/machine-users) in the Developer Guide for the precise signing protocol and request format.

## Assign to groups

Machine users and agents participate in the same group system as human users. Assign a machine user to groups to grant it vault capabilities.

1. After creation, or at any point later, navigate to **Users & Groups** and find the machine user on the **Users and Trading Machines** tab.
2. Click the row actions dropdown and select **Edit**.
3. Add the machine user to the appropriate groups from the multi-select list.
4. Save.

The machine user gains the capabilities of all its groups immediately. If a group is permitted to initiate signing for a specific set of keys, any machine user in that group can do the same.

:::tip
Create dedicated groups for machine users and agents rather than placing them in groups alongside human users. This makes it easier to audit, freeze, or reassign machine identities without affecting your human user policies.
:::

## Freeze a machine user

If an agent behaves unexpectedly or you need to halt its activity:

1. Find the machine user on the **Users and Trading Machines** tab.
2. Click the row actions dropdown and select **Freeze**.
3. Confirm. The machine user's signing requests are immediately rejected by the vault.

Unfreeze follows the same process. The freeze and unfreeze operations are governed by the **Freeze Keys** and **Unfreeze Keys** capabilities in Administrative Policy.

## Rotate credentials

### Rotate the API key

If the API key is compromised or you want to rotate it on a schedule:

1. Find the machine user in the list.
2. Click the row actions dropdown and select **Rotate API Key**.
3. The vault generates a new API key and shows it in a one-time reveal modal. Copy and store it immediately.
4. The old API key stops working. Update the credential in your systems before rotating.

### Rotate the Ed25519 public key

If you need to replace the Ed25519 key pair:

1. Generate a new Ed25519 key pair outside the vault.
2. Find the machine user and click **Edit** from the row actions dropdown.
3. Replace the stored public key with the new PEM-encoded public key and save.
4. Update the corresponding private key in your systems. The old key pair will no longer be accepted.

## View the audit log

From the **Users and Trading Machines** tab, click the row actions dropdown and select **View Audit Log**. The Audit Log page opens pre-filtered to that machine user's activity, showing all signing events and administrative actions it initiated.