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

# Set up governance

> Define your governance entities in the dashboard or with the API.

> [!NOTE]
>
> **PREMIUM ADD-ON** ✨
>
> Governance is available upon request only. Please [**contact us**](mailto:hello@getlago.com) to get access to this premium feature.

Setting up governance is a one-time step: you define the entities for your organization, and they apply to every customer. Create parents before their children.

> [tab] Dashboard
>
> ### Create an entity
>
> 1. Go to **Settings** > **Governance**.
> 2. Click **Add a governance entity**.
> 3. Fill in the fields, then click **Create governance entity**.
>
> ![The Create a governance entity drawer: Teams, hierarchical, parent Departments, with four attribution keys](https://mintcdn.com/lago-docs/ulhUx8P7BdGQu-pb/guide/governance/images/create-governance-entity.webp?fit=max\&auto=format\&n=ulhUx8P7BdGQu-pb\&q=85\&s=1dec1832c2741b19a77c25a81ca740d3)
>
> Create a governance entity
>
> * **Name** and **Code**: the code is how the API refers to the entity.
> * **Description** (optional).
> * **Type**: **Hierarchical** or **Flat**.
> * **Parent** (optional): hierarchical entities only. Leave it empty for the top of the tree.
> * **Attribution keys**: the event properties that carry the value. Type a key and press enter. Up to 4.
>
> Turn on **Create more** to add several entities in a row.
>
> ### View your entities
>
> The **Governance entities** list has one tab per type. The **Hierarchical** tab shows the tree, each entity indented under its parent:
>
> ![The Hierarchical tab: Departments, with Teams nested under it and Users nested under Teams](https://mintcdn.com/lago-docs/ulhUx8P7BdGQu-pb/guide/governance/images/governance-entities-hierarchical.webp?fit=max\&auto=format\&n=ulhUx8P7BdGQu-pb\&q=85\&s=6ea88c42ee387b8b25468687a351f440)
>
> Hierarchical entities
>
> The **Flat** tab lists the entities that sit outside the tree:
>
> ![The Flat tab: API Keys, Endpoints and Agents](https://mintcdn.com/lago-docs/ulhUx8P7BdGQu-pb/guide/governance/images/governance-entities-flat.webp?fit=max\&auto=format\&n=ulhUx8P7BdGQu-pb\&q=85\&s=423a93545b51a0bd00583a2c3cbff298)
>
> Flat entities
>
> ### Edit or delete an entity
>
> Open the entity's menu in the **Governance entities** list, then click **Edit entity** or **Delete entity**.

> [tab] API
>
> ### Create an entity
>
> `POST /api/v1/usage_attribution_types`
>
> ```bash Hierarchical theme={"dark"}
> curl --location --request POST "$LAGO_URL/api/v1/usage_attribution_types" \
>   --header "Authorization: Bearer $API_KEY" \
>   --header 'Content-Type: application/json' \
>   --data-raw '{
>     "usage_attribution_type": {
>       "code": "user",
>       "name": "User",
>       "role": "hierarchical",
>       "parent_code": "team",
>       "attribution_keys": ["user_id", "userId", "uid"]
>     }
>   }'
> ```
>
> ```bash Flat theme={"dark"}
> curl --location --request POST "$LAGO_URL/api/v1/usage_attribution_types" \
>   --header "Authorization: Bearer $API_KEY" \
>   --header 'Content-Type: application/json' \
>   --data-raw '{
>     "usage_attribution_type": {
>       "code": "api_key",
>       "name": "API key",
>       "role": "flat",
>       "attribution_keys": ["api_key"]
>     }
>   }'
> ```
>
> ```json Response theme={"dark"}
> {
>   "usage_attribution_type": {
>     "lago_id": "7b0d2f6e-3c1a-4f7b-9a52-1e8c4d6f0a21",
>     "lago_organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
>     "code": "user",
>     "name": "User",
>     "description": null,
>     "attribution_keys": ["user_id", "userId", "uid"],
>     "role": "hierarchical",
>     "lago_parent_id": "c5e1b8a4-92d7-4e0f-8b3a-6f2d1c9e7a54",
>     "parent_code": "team",
>     "created_at": "2026-10-01T09:00:00Z",
>     "updated_at": "2026-10-01T09:00:00Z"
>   }
> }
> ```
>
> | Field | Description |
> | - | - |
> | `code` | Required. Unique in your organization. |
> | `name` | Display name. |
> | `description` | Optional. |
> | `role` | Required. `hierarchical` or `flat`. |
> | `parent_code` | Optional, hierarchical only. Must be an existing hierarchical entity. |
> | `attribution_keys` | Required. 1 to 4 event property names. A key belongs to one entity only. |
>
> ### List, retrieve, update and delete
>
> | Operation | Endpoint |
> | - | - |
> | List | `GET /api/v1/usage_attribution_types` (filter with `role` and `search_term`) |
> | Retrieve | `GET /api/v1/usage_attribution_types/:code` |
> | Update | `PUT /api/v1/usage_attribution_types/:code` |
> | Delete | `DELETE /api/v1/usage_attribution_types/:code` |

## Rules

* You can always change the name, description and attribution keys. New keys apply to new events only.
* Once usage is attributed to an entity, its code, role and parent are locked (`usage_already_attributed`).
* A flat entity has no parent, and an entity with children can't become flat.
* Deleting an entity stops attribution from now on. Billing isn't affected.

> [card] [Send attributed events](https://getlago.com/docs/guide/governance/sending-events.md)
>
> Tag events with entity values.

> [card] [Query attributed usage](https://getlago.com/docs/guide/governance/query.md)
>
> Read usage and spend per entity.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.