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
organization
├── projects
│ └── agents, environments, secrets, sites and service accounts
├── members, groups and service accounts
├── providers, models, connections and secrets
└── policies, quotas and billingAn 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
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
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
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 doesn't remove it at once. Its state becomes DELETE_REQUESTED, and kosem purges it after a grace period.