> ## Documentation Index
> Fetch the complete documentation index at: https://www.plain.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Machine users

> Set up your agent's identity in Plain.

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

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/acting-on-threads#suggest-a-reply) for a teammate 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 labelling 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:

    ```text 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 a number of benefits:

* **A clear author for every message.** Customers and teammates 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.
* **Easy rotation.** 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/routing).

## Finding your machine user's ID

You'll often want 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/routing)).

The ID is visible in the Plain UI on your machine user's page under **Settings → Machine Users**. The easiest approach is to 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 individual agents that do narrow tasks can often be easier to build and manage.