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

# Users and groups

> Waystone comes with built-in user management and tracking for your LLM application.

When you make a model request through Waystone,
you can optionally provide a unique identifier for the end-user
triggering that request
to allow Waystone to handle per-user usage tracking.
This allows you to:

* Set quotes on users, groups, or a combination (e.g. no single user in group X can take more than 10% of monthly credits)
* Monitor model usage to track down service abuse
* Apply special rules on important users (additional model output checks; model routing etc.)

## Entities

Waystone allows you to define:

* `user` (individuals)
* `group` (e.g. orgs or teams)
* a `user` and a `group`

Once a request is sent with both a `user` and a `group`,
Waystone creates a link between the entities: "user is part of group";
such requests are attached to both the user *and* the group,
and is subject to rules and conditions
on both.

Once a user is attached to a group,
however,
any request with **just** the user provided
will **only** be applied to that user.

### Metadata

You can attach arbitrary metadata to each user and group,
which is then used to apply [`rulesets`](./rules/rulesets).
Useful metadata for your application may include:

* region
* payment plan / tier of product
* categories of note, such as "risky" or "vip"

## Tracking usage

To attach a request to an entity,
provide the unique ID for the user or group *in your application*
when making the request.
The Waystone API is a superset of the OpenAI API,
so the `metadata` field is used to also provide user identification in user requests:

<CodeGroup>
  ```typescript query.ts theme={null}
    const client = new OpenAI({
      apiKey: process.env["WAYSTONE_API_KEY"],
      baseURL: "https://waystone.run/api/gateway/v1",
    });

    const userMetadata = {
      user: { id: userId, metadata: { tier: "free" }},
    }

    const response = await client.responses.create({
      model: "openai/gpt-4.1-mini",
      input: "Your super special prompt",
      metadata: { waystone: JSON.stringify(userMetadata) }
    });
  ```

  ```python query.py theme={null}
  client = OpenAI(
      api_key=os.environ.get("WAYSTONE_API_KEY"),
      base_url="https://waystone.run/api/gateway/v1",
  );

  userMetadata = {
    "user": { "id": userId, "metadata": { "tier": "free" }},
  }

  response = client.responses.create(
      model="openai/gpt-4.1-mini",
      input="Your super special prompt",
      metadata={ waystone: json.dumps(userMetadata) }
  );
  ```
</CodeGroup>

In this example,
the request is attached to a user,
which is simulatanously given some additional metadata.

Refer to the [API](./api-reference) for more information.

## Taking Action on Users

Waystone's concept of [`rulesets`](./rules/rulesets)
allows you to automatically take actions on users or groups
by their metadata.

<Card title="Rulesets" icon="list-tree" href="/rules/rulesets">
  Learn how to group users and take action on user requests by their metadata.
</Card>

## Exploring usage

Functionality around exploring entity usage is under development
with Waystone beta users.
This includes:

* OTEL on model inputs and outputs
* Tracking usage (tokens; requests; USD cost)
* Usage analysis (spikes, abuse detection, etc.)

To gain access to usage tracking,
please [get in touch](mailto:support@waystone.run).