# Catalog permissions

Each part of Catalog follows its own permission: who may read and change the declared services, who may read what agents and cloud accounts observed, and who may manage environments. Agents and cloud accounts belong to the organization, so their permissions are the organization's. The same identifiers are the scopes of an [API key](https://docs.evohub.io/api-keys-and-scopes.md).

## The permissions

| Permission | Covers |
| --- | --- |
| `catalog:component:read` | Services, their tiers, SLA and RACI, the tiers and their versions, and SLA reports. |
| `catalog:component:write` | Declaring, changing and deleting services, setting their RACI and SLA overrides, and creating, editing, reordering and archiving tiers. |
| `catalog:resource:read` | What agents and cloud accounts observed: resources, their history and changes, applications, namespaces, images and the map. |
| `catalog:resource:write` | Deciding which service a resource or an application belongs to: accepting and rejecting match proposals, and choosing a service by hand. It never creates or edits a resource. |
| `catalog:source:read` | Environments, and the agents and cloud accounts reporting into them. |
| `catalog:source:write` | Creating, changing and deleting environments, and renaming, pausing and resuming a source. Also needed to enroll an agent or connect a cloud account, because that decides which environment its inventory lands in. |
| `identity:agent:read` | Seeing the organization's agents under **Organization → Agents**. |
| `identity:agent:write` | Creating enrollment tokens, renaming and revoking agents. |
| `identity:cloudaccount:read` | Seeing the organization's cloud accounts. |
| `identity:cloudaccount:write` | Connecting, changing, checking, pausing and disconnecting cloud accounts. |

Some pages combine two halves and need both:

| To | You need |
| --- | --- |
| See the match queue | `catalog:component:read` and `catalog:resource:read` |
| See drift, or export the inventory | `catalog:component:read` and `catalog:resource:read` |
| See a service's resources | `catalog:component:read` and `catalog:resource:read` |
| Accept a proposal that creates a new service | `catalog:resource:write` and `catalog:component:write` |
| Enroll an agent | `identity:agent:write` and `catalog:source:write` |
| Connect a cloud account | `identity:cloudaccount:write` and `catalog:source:write` |
| See a cloud account's architecture | `identity:cloudaccount:read` and `catalog:resource:read` |

A service's page needs only `catalog:component:read`. Without `catalog:resource:read`, what the agents found is left out of it rather than refused, and the page says which permission would show it.

There is deliberately no permission to send inventory. Only an enrolled agent, signing each request with its own key, can report into Catalog; an API key or a person never can.

## Default roles

| | Viewer | Member | Admin |
| --- | --- | --- | --- |
| See services, tiers, SLA reports, resources, the map, drift, environments, agents and cloud accounts | Yes | Yes | Yes |
| Declare and change services, their RACI and tiers | — | Yes | Yes |
| Accept and reject matches, choose a service by hand | — | — | Yes |
| Manage environments | — | — | Yes |
| Enroll and revoke agents, connect cloud accounts | — | — | Yes |

Owners and Admins acting in person pass every check. API keys are held to their scopes, even when an administrator created them.

## Ready-made Catalog roles

The role editor (**Organization → Roles**) offers three levels for Catalog:

| Level | Can | Cannot |
| --- | --- | --- |
| **Viewer** | See services, what the agents and cloud accounts found, environments, the map and drift. | Declare or change a service, accept a match, install an agent or connect a cloud account. |
| **Service Owner** | Everything a Viewer sees, plus declare services: owner, tier, runbook and who is responsible. | Accept a match, change environments, install an agent or connect a cloud account. |
| **Catalog Admin** | Everything: services, matches, environments, installing agents and connecting cloud accounts. | Manage the organization's members, roles or billing. |

See [Roles and permissions](https://docs.evohub.io/roles-and-permissions.md) for building custom roles.

## Related

- [Catalog overview](https://docs.evohub.io/catalog-overview.md)
- [API keys and scopes](https://docs.evohub.io/api-keys-and-scopes.md)
- [Catalog API](https://docs.evohub.io/catalog-api.md)