Users and access
A person holds a role in each group. Super admins are global. One person can be a Group Admin of one group, a Viewer of three and an MCP User of two more.
| Role | May |
|---|---|
| Super admin | Everything: users, groups, zones, sizes, API keys, backups, audit, config, the OAuth clients, the service-account rules |
| Group admin (per group) | Environments, deploys, worker counts, secrets, MCP keys, IP rules, throttles, rebalance, the group's members below admin, requests for its zones' identities, the group's restrictions |
| Viewer (per group) | Read: the repo, load, packages, deploy jobs and logs. Not the Secrets page |
| MCP user (per group) | Sign in and approve an OAuth MCP client for a zone of the group. One page in the console, and /api/v1/me. Nothing else |
Group admins cannot approve their own permission requests, grant a role above their own, or see other groups. A person with no membership anywhere sees only their own account page.
Since 1.0.0c the console has more per-group sections; the same rule applies to each — edit is a super admin or
that group's admin, view is any member of the group, a member of another group is refused (403):
| Section | Super admin | Group admin | Viewer | MCP user |
|---|---|---|---|---|
| LLM providers (Config page, org scope) and their model lists | edit | — | — | — |
| LLM providers (group) and their model lists | edit | edit | — | — |
| Evals, Scans, Guardrails cards (Required, Gate, provider, model) | edit | edit | — | — |
| Group page: packages, apps and skills per zone, deploy badges | view | view | view | — |
| Scan report of a deploy, app preview | view | view | view | — |
LLM configs page and Accept (POST /api/v1/groups/<g>/configs/accept) |
accept | accept | accept | accept |
Telemetry ingest POST /otlp/v1/* |
with a session naming the group, an MCP key, or a user token: any member |
A devops API key follows the role and groups it was minted with on the API routes; an agent key (rmk_) is a
worker credential and is refused by every console route. The ingest takes a bearer only (a person's OAuth token, an
MCP key, or a console session naming its group in ramen-group); console API keys are not telemetry credentials.
Every row is asserted per role by the local security matrix (tests/conformance/test_security_matrix.py) and on each
cloud by the auth matrix (tests/cloud/test_auth_matrix.py).
Custom roles
Since 0.7.5 a super admin can define roles of their own on the Config page's Roles card (or
PUT /api/v1/config/roles/<name>). A custom role has a base, one of Group Admin, Viewer or MCP User, which is
what the console lets it do; a label; and an OAuth only switch. Its name is what makes it useful elsewhere:

analyst on the Viewer base.- Per-tool access (groups and zones) can list or call a tool for
analystwithout opening it to every viewer. A caller with a custom role matches a tool-access entry that names the role or its base, so a custom role never has less than its base. The list also offers Evals Job (kindevals): the repo's own evals, run against the canary before a deploy goes live. Leave it out of a rule and that tool is hidden from the evals too — its cases error withTool <name> not found— so add it where the evals test a restricted tool.keyandevalsare reserved: no custom role may use those names. - Identity provider rules (Entra ID and Workspace) can map a provider group straight to it.
- OAuth only: a person holding the role in any group cannot sign in with a password or a magic link; the login
page answers
403 This account signs in with <provider>. The built-in roles cannot be made OAuth-only.
The person's token carries the custom role name, so workers enforce it on both transports. Workers learn the
roles and their bases (RAMEN_ROLES) on the group's next deploy, like per-tool access: until then a new role
matches no tool-access entry on that worker (it fails closed). Deleting a role that a
membership, a provider rule or a tool-access entry still uses is refused (409) until those are changed. Names are
lowercase, a-z0-9_, start with a letter, 2 to 32 characters, and may not shadow a built-in.
Where a membership comes from
Each membership shows its source on the Users page: set here for what an admin gave on this page or through
PUT /api/v1/groups/<g>/members/<uid>, via
The Users page
One member table per group with a role dropdown, Remove and Add member by email, then the account table
and the pending permission requests. Super admins create accounts with a password; group admins add existing
accounts to their groups and reset their members' passwords. Accounts that sign in through an identity provider
show Signs in through

Passwords need twelve characters with four character classes. Failed sign-ins are rate-limited per address and audited.
How a person signs in
Password sign-in is on by default. Magic-link sign-in (a one-time link by email) is off until a super admin switches
it on on the Config page, and needs mail configured. A super admin can add Microsoft Entra
ID or Google Workspace on the Config page and map claim values to roles per group; see
Entra ID and Workspace. Disabling password
login needs another way in first, or the break-glass RAMEN_ADMIN_FORCE_PASSWORD=1.
Every role, group and password change bumps the person's session epoch, so open sessions and refresh tokens end at once and an open tab never keeps a permission it just lost.
Since 1.0.0 (D92) their MCP access tokens end at once too. Workers check a token offline, so the console pushes a revocation to the workers of every group the person holds a token for: tokens issued before that moment are refused within seconds, and the client signs in again (only if the person still may). The triggers:
- removing a membership, changing a role, setting a password, deleting the user, revoking an approved request;
- Sign out everywhere:
POST /api/v1/users/me/sign-outfor yourself, or/api/v1/users/<id>/sign-outfor anyone whose account you manage — it ends console sessions and OAuth tokens alike; - a client revoking its own token (RFC 7009
POST /oauth/revoke), a replayed refresh token (the whole grant), and deleting an OAuth client on the Config page.
A token's life is RAMEN_OAUTH_ACCESS_TTL (default one hour); revocation entries are kept no longer than that. A zone
the console cannot reach keeps accepting the token until the retried push lands (the group page says
Revocation pending), or until the token expires.
What an MCP user gets
An MCP user who signs in sees one page: which groups they may connect to and how. Claude Code over HTTP, and Claude Desktop, Cursor or VS Code through the bridge, send them to the console to sign in and approve the client once per group and zone. Every call is logged under their account. Connect with OAuth and connect with a password show both sides.

Service-account permissions
Each zone's workers run as their own cloud identity: a GCP service account with Workload Identity, an AWS IAM role with IRSA, or an Azure user-assigned managed identity with workload identity. It starts with the least it needs: read the group's prefix of the bucket and the group's secrets. Everything more is requested and approved.
- A super admin sets the rules on the Config page:
deny kms.*style rules that gate what anyone may request. Deny wins; when allow rules exist a permission must match one. A group admin can add stricter restrictions on the group page. - A group admin requests on the group page: a zone, a permission from the catalogue and a scope. Empty
or
*means the group's own area. Named buckets or secrets bind the permission to those alone. - Another admin of the group, or a super admin, approves. The console binds the cloud roles and records the permission and its scope on the zone.
- Revoke on the badge takes it back and unbinds exactly what was bound.
bucket.readandsecrets.readkeep the baseline the worker needs to load its own code.
| Permission | GCP | AWS | Azure |
|---|---|---|---|
bucket.read, bucket.write |
roles/storage.objectViewer or objectUser on the group prefix or the named buckets |
s3:GetObject, ListBucket or PutObject, DeleteObject on the prefix or the named buckets |
Storage Blob Data Reader or Contributor (the container: Azure cannot scope to a prefix) |
secrets.read |
secretAccessor on the group's secrets or the named ones |
GetSecretValue on the group's path or the named secrets |
Key Vault Secrets User on each of the group's secrets |
logs.write, metrics.write, pubsub.publish, queue.consume, datastore.user, kms.decrypt, ai.user |
project-wide roles; need console_project_iam = true in Terraform |
account-wide actions on the role's inline policy | Log Analytics Contributor, Monitoring Metrics Publisher, Service Bus Data Sender / Receiver, Storage Table Data Contributor, Key Vault Crypto User, Cognitive Services User, in the install's resource group |
Every request, approval and revoke is audited with the user, group and permission as tags.
Audit and logs
Audit (super admins) keeps every console action with the user, address, outcome and tags, failed sign-ins included. The newest hundred are on the page with a search box and an outcome filter; CSV and JSON downloads give the whole log.
Logs shows each worker's access log: one JSON line per MCP call with the time, address, method, tool name,
status and the key id or user:<id>. Entries are newest first on the left and the selected one opens on the
right. In the cloud it reads Cloud Logging, CloudWatch, or on AKS the pod logs through the Kubernetes API. The
verbose flag on an environment logs full request and response bodies; turn it on only while debugging.

