Team Roles

Every member of a project holds one role: viewer, developer, admin or owner. The roles are nested — each can do everything the one before it can, and more. The control panel calls the developer role Member.

The API enforces the same rules as the control panel, whichever way you call it: from the browser, the CLI, an SDK, Terraform or a direct request. A request your role does not allow is refused with 403 INSUFFICIENT_ROLE.

At a Glance

The payment method, refunds of the credit balance, service agreements and handing billing responsibility to someone else belong to the biller. Anyone else is refused with 403 BILLER_ONLY. Billing can only be handed to an admin or owner, and the biller cannot be moved below admin until they have handed billing on.

Viewer

Read-only access to everything in the project: its apps, servers, databases, Redis, storage, registries, domains, email, hosting, webhooks and integrations; logs, metrics and deployment history; members and pending invitations; the names and metadata of secrets (never their values) and the values of variables; API keys and service accounts (never the keys themselves); and the project's costs, billing summary and invoices.

A viewer can also ask the biller to add a payment method, and run read-only queries in the database console.

Developer

Everything needed to build and run the project's software. A developer can create, change, deploy, roll back, restart and delete:

• apps, including opening a shell in a running container;
• servers and SSH keys;
• databases and Redis, including browsing and editing their data;
• storage buckets, their files and their access credentials;
• container registries, repositories and images;
• domains and DNS records, but not buying a domain, which is an immediate, non-refundable charge;
• email sending domains, forwarders, SMTP credentials and templates, and sending email;
• web hosting sites, their files, domains, databases and backups;
• webhooks, resource groups, and integrations such as git providers and your own DNS connection.

Resources a developer creates are billed to the project as usual, so a developer can add to the project's bill. Resizing a resource, or changing a setting that belongs to one resource, such as a bucket's overage limit, is part of managing that resource.

A developer cannot change anything about the project as a whole: its members and invitations, its plans and the billing email, its service accounts and API keys, its secrets and variables, or its name. A developer cannot delete the project.

Admin

Everything a developer can do, plus:

• invite members, cancel invitations, remove members and change their roles — except that only an owner can grant the owner role, or change or remove an owner;
• create, change and delete secrets and variables, and read a secret's audit log;
• create, change, rotate and delete service accounts and their API keys;
• change the email plan and the monthly cap, buy a secrets pack, and buy domains;
• set the billing email and rename the project.

Owner

Everything an admin can do, plus deleting the project and managing the owner role. Until billing responsibility is handed to someone else, the first owner is also the biller.

API Keys and Tokens

A credential never does more than the role behind it.

• A project API key acts with the role of its service account, which can be viewer, developer or admin, never owner. A key on a developer service account can deploy apps, but cannot change secrets or invite members, whatever scopes it carries.
• A personal access token and a CLI login act with your own role in each project.

The key's scopes apply on top of the role: a request needs both a role that allows it and, for an API key, the scope that covers it. A missing scope is 403 INSUFFICIENT_SCOPE; a role that does not allow the request is 403 INSUFFICIENT_ROLE.

Some actions need a person signed in to the control panel whatever their role, such as inviting members or creating API keys. See What a Key Can Reach.

INSUFFICIENT_ROLE

403 — your role in the project does not allow this request. The details field names what was needed:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_ROLE",
    "message": "This needs an owner or admin of the project. Ask a project owner or admin to change your role, or the role of the service account your API key acts as.",
    "details": { "permission": "billing:update", "requiredRole": "admin", "role": "developer" },
    "docsUrl": "https://cosmoner.com/docs/guides/team-roles#insufficient_role"
  }
}

Retrying will not help. Ask an owner or admin of the project to change your role under Project → Members, or, for an API key, the role of its service account under Project → API Keys.