Skip to Content
kosemdocs
Concepts

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 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

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:

NameExampleChangesUse it for
IDprj_01m5r9dh9mf0ps98ktkap3562cNeverAPI calls and scripts
SlugplaygroundNeverThe console's URLs. It's unique across kosem.
Display namePlaygroundYesWhat 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:

ResourceName
An organizationorganizations/org_…
A projectprojects/prj_…, with the organization in its parent field
Something in a projectprojects/prj_…/agents/ags_…
Something in eitherorganizations/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.

On this page