> ## Documentation Index
> Fetch the complete documentation index at: https://plain-docs-orca-916-agent-docs-restructure.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Machine users

> Give your agent its own identity in Plain, so its actions are attributable and permissioned.

In Plain, an agent is represented as a **machine user**. This is the same primitive used for any automation or integration, but it's the right home for an agent because it gives your agent a name, an avatar, and an audit trail that's distinct from any human user.

Machine users can be assigned threads, can reply to customers, can be @-mentioned, and show up in the timeline as the author of any message they send. When a customer sees a reply from your agent, they see the machine user's **public name** and avatar.

## Create a machine user

<Steps>
  <Step title="Add the machine user">
    Go to **Settings** → **Machine Users** and click **+ Add Machine User**.

    Two fields matter:

    * **Name**: only visible to your team. Use this to describe what the agent does, e.g. *"Support Agent"* or *"Tier 1 Triage Bot"*.
    * **Public name**: visible to customers when the agent sends a message, e.g. *"Plainey"* or *"Acme Support"*.

    You can also upload an avatar, which appears next to messages sent by the agent.
  </Step>

  <Step title="Create an API key">
    From the machine user's page, click **+ Add API key** and pick the permissions your agent needs.

    Common permissions for an agent that reads threads and replies to customers:

    * `thread:read`: read threads and timelines
    * `thread:reply`: send replies via `replyToThread`
    * `generatedReply:create`: add [suggested replies](/agents/support-agent) for a user to review
    * `thread:assign` and `thread:unassign`: for handoffs between the agent and humans
    * `customer:read`: look up customer context before replying

    If your agent does more, like labeling threads, marking them as done, or creating events on customers, add the matching permissions.

    Copy the API key once it's created. You won't be able to see it again.
  </Step>

  <Step title="Use the API key">
    The API key goes in the `Authorization` header of every GraphQL request:

    ```plaintext theme={null}
    Authorization: Bearer plainApiKey_xxx
    ```

    With the [GraphQL SDK](/graphql/sdk):

    ```ts theme={null}
    import { PlainClient } from "@team-plain/graphql";

    const plain = new PlainClient({ apiKey: process.env.PLAIN_API_KEY! });
    ```
  </Step>
</Steps>

## Why use a machine user

Machine users give you three things:

* **A clear author for every message.** Customers and users can tell at a glance which messages came from the agent.
* **Independent permissions.** You can scope the agent's API key narrowly without touching what your team can do.
* **Rotation without downtime.** You can issue and revoke API keys for the machine user without disrupting access as machine users can have more than one API key.
* **Per-agent assignment.** Threads can be assigned to a machine user directly. See [routing](/agents/support-agent).

## Finding your machine user's ID

You need your machine user's ID in code, for example to check whether a thread is assigned to your agent before acting on it (see [routing](/agents/support-agent)).

The ID is on the machine user's page under **Settings → Machine Users**. Copy it and set it as an environment variable.

## Multiple agents

You can create as many machine users as you want, one per agent. Smaller agents that do narrow tasks are less work to build and manage.