# Organizations and projects

How kosem arranges everything in organizations and projects, and how the API names what's in them.

Everything on kosem belongs to an organization, and most of it to one of the organization's projects. This page explains the hierarchy, why it has two levels, and how the API names resources.

## The hierarchy [#the-hierarchy]

```text
organization
├── projects
│   └── agents, environments, secrets, sites and service accounts
├── members, groups and service accounts
├── providers, models, connections and secrets
└── policies, quotas and billing
```

An **organization** is your company's boundary on kosem: its people, its bill, its keys and connections to outside services and its policies. A **project** is a unit of work in it, such as a product, a team or an experiment.

## Why two levels [#why-two-levels]

Access is granted at either level:

- A role granted on the organization holds in every project. An Owner of the organization is an Owner of each of its projects.
- A role granted on a project holds only there.

So you set what's common once, on the organization, and give each team a project with only the access it needs.

Some resources can belong to either level, and where they live decides who manages them:

- **Secrets.** An organization's secret can be shared with its projects, so you keep one copy of a value that many projects use.
- **Service accounts.** A project's account is managed by the project's Owners and is deleted with the project. An organization's account works across projects, and only people with roles on the organization manage it.

## IDs, slugs and display names [#ids-slugs-and-display-names]

Organizations and projects each have three names:

| Name         | Example                          | Changes | Use it for                                    |
| ------------ | -------------------------------- | ------- | --------------------------------------------- |
| ID           | `prj_01m5r9dh9mf0ps98ktkap3562c` | Never   | API calls and scripts                         |
| Slug         | `playground`                     | Never   | The console's URLs. It's unique across kosem. |
| Display name | Playground                       | Yes     | What people read                              |

kosem generates every resource's ID. IDs start with their type, such as `org_` for organizations, `prj_` for projects and `ags_` for agents, and they're never reused.

## Resource names [#resource-names]

The API names each resource by its path of IDs:

| Resource               | Name                                                                  |
| ---------------------- | --------------------------------------------------------------------- |
| An organization        | `organizations/org_…`                                                 |
| A project              | `projects/prj_…`, with the organization in its `parent` field         |
| Something in a project | `projects/prj_…/agents/ags_…`                                         |
| Something in either    | `organizations/org_…/secrets/sec_…` or `projects/prj_…/secrets/sec_…` |

Paths take IDs, never slugs. To find an ID from a slug, look the slug up: `GET /v1/projects/lookup` and `GET /v1/organizations/lookup`.

## Deleting a project [#deleting-a-project]

Deleting a project doesn't remove it at once. Its state becomes `DELETE_REQUESTED`, and kosem purges it after a grace period.

## Related [#related]

- [Identity and access](/concepts/identity-and-access)
- [API conventions](/reference/api-conventions)
