Skip to Content
kosemdocs
Concepts

Identity and access

Who can use kosem and what each can do. People, groups and service accounts get roles on organizations and projects.

kosem decides what anyone can do with roles granted on organizations and projects, in the style of Google Cloud's IAM. This page explains the parts and how they combine.

Who gets roles

Roles are granted to three kinds of principal:

  • People, as members or guests of an organization. People join an organization only by invitation.
  • Groups of the organization's members and of its other groups. A role granted to a group reaches everyone in it, however deeply groups are nested.
  • Service accounts, which are identities for software. Software calls the API with a service account's API key.

Agents aren't principals, and nobody grants an agent a role. What an agent can do comes from its configuration, such as its model and tools, and from the secrets people grant it.

What roles grant

A role is a set of permissions, named for what it lets people do, such as Secret Accessor or Member Admin. Three basic roles hold in every product:

  • Owner: everything, including who has access.
  • Editor: creating and changing resources, but not access.
  • Viewer: reading.

Products add roles of their own, such as Agents Admin, LLM Gateway User and Billing Admin. Roles lists every predefined role, and in the console the organization's Settings › Roles page shows each role and its exact permissions.

Where roles hold

A role is granted on a resource, and holds there and on everything in it:

  • Owner granted on the organization holds in every project.
  • Owner granted on a project holds only in that project.

So kosem has no Organization Admin or Project Admin role: there's Owner, granted on one or the other. Roles that hand out part of the organization's administration, such as Billing Admin or Member Admin, divide it by what they do instead.

Private agents

An agent can be private. A private agent doesn't take its project's roles, and only the people it's shared with can see it.

What you see

Lists return only what you can see. A list of projects returns the projects you have a role on, and doesn't name or count the others. The console hides the actions you can't take, and the API checks every call regardless.

A role you grant or remove applies within about a second. Removing someone from an organization removes every role they had in it.

Service accounts

A service account belongs to an organization or to one of its projects. Where it lives decides who manages it; what it can do comes only from its roles, which can be granted anywhere in its organization.

  • API keys start with kosem_sk_, and kosem shows each only once. Keys expire after 90 days by default and after a year at most, and an account has at most 10.
  • Creating keys takes Owner, or Service Account Key Admin on that account. Editors can create service accounts but not keys, since a key acts with its account's roles.
  • Stopping keys: deleting a key, or disabling its account, stops it at once.

A project's Owners can create keys for the project's service accounts. So if you grant a project's account a role on the organization, or on another project, the project's Owners can act there through it. The console warns you before you do.

On this page