Roles and API keys
An organization is RunMat's tenant: it owns projects, members, clusters, packages, the plan and its limits. Projects belong to one organization. This page covers organization and project roles, adding people, service accounts and API keys.
Organization roles
| Role | Can |
|---|---|
owner | Everything an admin can, plus the organization's highest-impact settings. SCIM never changes owners. |
admin | Manage members and invitations, roles, API keys and service accounts, SSO and SCIM, clusters and execution policy, packages, and every project in the organization. |
member | Read and write every project in the organization, create projects, run code and submit remote runs. |
viewer | See the organization. Access to a project needs an explicit project membership. |
Project roles
A project membership grants read or write on one project. Owners, admins and members already have access to every project in their organization, so project memberships matter for viewers and for people from outside the organization. Use separate organizations for groups that must not see each other's projects; a member of an organization can open all of its projects.
Add people
- Invite the person from organization administration (
POST /v1/orgs/{orgId}/memberships/invite), or provision them with SCIM. - Give the lowest role that covers their work. Most people need
member. - For a viewer or outside collaborator, add a project membership with
readorwrite. - To remove someone, remove their organization membership. Their sessions stop authorizing requests for the organization, and API keys they own stop working. Copies of files they downloaded remain wherever they put them.
Invitations and notices are delivered by email through an email delivery service configured on the server. A server with no email delivery configured does not send them. Servers can also send through your own SMTP relay. On a network with no email delivery, provision users through SCIM.
Each person may register up to the plan's number of computers (Professional: three; Enterprise: no limit unless the contract sets one). Desktop, the CLI and compute nodes register the computer on first sign-in or connection. A person past the limit removes a computer in account settings.
Service accounts and API keys
Automation such as CI pipelines, scheduled jobs, compute-node provisioning and integrations authenticates with an API key. Each key belongs to a service account, so automation never shares a person's credentials.
Create a key in organization administration or with POST /v1/orgs/{orgId}/api-keys:
{
"name": "ci-signal-tools",
"role": "member",
"project_id": "proj_…",
"expires_at": "2027-06-30T00:00:00Z"
}| Field | Meaning |
|---|---|
name | What the key is for. Shown in the key list. |
role | The organization role the key acts with. |
project_id | Optional. Limits the key to one project; requests for other projects are refused. |
expires_at | Optional expiry time. |
The response contains the key once, in the form rk.live.<key-id>.<secret>. The server stores only the key ID and a keyed hash of the secret, so a lost key cannot be recovered; create a new one. DELETE /v1/orgs/{orgId}/api-keys/{apiKeyId} revokes a key and removes its service account. Only owners and admins manage keys.
Use a key from automation:
export RUNMAT_SERVER_URL=https://runmat.example.com
export RUNMAT_API_KEY='rk.live.…'
export RUNMAT_PROJECT_ID=proj_…
runmat --locked run src/main.mPractices:
- One key per pipeline or integration, scoped to one project where possible, with an expiry.
- The lowest role that works. A pipeline that reads and writes one project needs
memberwithproject_id. - Store keys in your CI system's or vault's secret store and mask them in logs. Never put a key in project files, notebooks or
runmat.toml. - Record each key's owner, purpose and rotation date.
- Rotate by creating the replacement, deploying it, confirming it works, then revoking the old key.
Usage made with a key counts against its owner's allowance, and a key stops working when its owner leaves the organization.
Authorization model
Every request is authorized on the server, whatever the client shows: the credential identifies the person or service account, the request names the organization and project, and the server checks the role, the project membership, the key's project scope and the organization's plan. Resource IDs, signed URLs and display names grant nothing by themselves.
A person in several organizations acts within the organization selected for each request. If a client seems to show the wrong projects, check the selected organization first; the CLI takes --org or RUNMAT_ORG_ID.
Audit records
Changes to memberships and roles, API keys, clusters and nodes, packages and project files are recorded as audit records with the actor, action, resource and time.
Avoid
- Creating team work in a personal organization and expecting team settings to apply.
- Making someone an admin for a task that
membercovers. - Running CI with a person's API key or session.
- Assuming that removing a member deletes copies they exported.