> ## Documentation Index > Fetch the complete documentation index at: https://docs.sfcompute.com/llms.txt > Use this file to discover all available pages before exploring further. # Roles > Define a policy of allowed actions This feature is in [public preview](/preview/roadmap). SF Compute uses role-based access control (RBAC). A role is a named set of permissions that defines what actions the holder can perform. A [grant](/preview/grants) assigns a role to a user or token within a workspace or across the organization. When a request arrives, SF Compute collects the caller's grants, evaluates the rules from every matched role, and allows the action only if a rule matches. Otherwise it is denied. Role names are slugs, unique within the organization. Roles are organization-wide. The same role can be granted across multiple workspaces. ## Creating a role Write a role definition in TOML and pass it to the CLI. ```bash theme={null} sf roles create --name training-operator -f role.toml ``` ```toml theme={null} api_version = "roles/v1" description = "Can manage instances and view pools" [[rules]] effect = "allow" [rules.actions] instance = ["*"] pool = ["read"] ssh_key = ["*"] secret = ["read"] ``` `api_version` must be `roles/v1`. `actions` is a map from resource name to a list of verbs. Use `"*"` as either the verb or the resource for a wildcard. A role grants nothing on its own. [Create a grant](/preview/grants) to assign it to a user or [token](/preview/tokens). ## Rule syntax A rule says what a user or token is allowed to do. It has two pieces: 1. An `actions` map, which pairs each resource (such as `instance` or `pool`) with a list of verbs (such as `read` or `write`). 2. An `effect` that says what to do about those actions. Only `allow` is currently supported. ```toml theme={null} api_version = "roles/v1" description = "Instance management" [[rules]] effect = "allow" [rules.actions] instance = ["read", "write", "delete", "list"] ``` ### Supported resources and verbs Resources: `instance`, `instance_template`, `image`, `pool`, `secret`, `ssh_key`, `firewall`, `role`, `grant`, `token`, `billing`, `order`, `limits`, `user`, `*` Verbs: `read`, `write`, `delete`, `list`, `create`, `*` Each rule covers every `(resource, verb)` pair you list. Use `"*"` as either the resource or the verb for a wildcard. Common patterns: ```toml theme={null} instance = ["read"] # Read instance details instance = ["write"] # Create or update instances instance = ["delete"] # Delete instances instance = ["*"] # All instance actions pool = ["read"] # View pool details pool = ["write"] # Create pools, attach schedulers order = ["read"] # View orders order = ["write"] # Place buy/sell orders billing = ["read"] # View balance, usage, invoices, rates billing = ["write"] # Create and manage budgets limits = ["read"] # View hard and soft limits limits = ["write"] # Set and remove soft limits secret = ["read"] # Read secrets from metadata service firewall = ["*"] # Manage firewalls token = ["*"] # Manage tokens ssh_key = ["*"] # Manage SSH keys "*" = ["*"] # Everything (equivalent to admin) ``` If no rule matches, the action is denied. ## Built-in roles SF Compute provides built-in roles that cover common patterns. ```bash theme={null} sf roles list ``` ``` NAME TYPE DESCRIPTION admin built-in Full access to all resources in the workspace viewer built-in Read-only access to all resources operator built-in Infrastructure management, no IAM access billing built-in Billing and orders only, no infrastructure member built-in Standard org member: read-only across non-sensitive resources training-operator custom Can manage instances and view pools ``` Built-in roles cannot be modified or deleted. ### Admin role Full access to all resources. Use sparingly. ```toml theme={null} api_version = "roles/v1" description = "Full access to all resources" [[rules]] effect = "allow" [rules.actions] "*" = ["*"] ``` ### Viewer role Read-only access to all resources. Cannot make any changes. ```toml theme={null} api_version = "roles/v1" description = "Read-only access to all resources" [[rules]] effect = "allow" [rules.actions] "*" = ["read", "list"] ``` ### Operator role Full access to infrastructure resources — instances, instance templates, images, pools, secrets, firewalls, SSH keys, and more — with no access to IAM (roles, grants, tokens) and no broader read access. ### Billing role Access to billing and orders only. No infrastructure access. Good for finance teams. ```toml theme={null} api_version = "roles/v1" description = "Billing and orders only" [[rules]] effect = "allow" [rules.actions] billing = ["*"] order = ["*"] limits = ["read"] ``` ### Member role Read and list access across non-sensitive resources, with no access to secrets, billing, tokens, or SSH keys. This is the default role users hold when they join an organization. ## Listing and inspecting roles ```bash theme={null} sf roles list sf roles get training-operator ``` ## Updating a role ```bash theme={null} sf roles set training-operator -f role-v2.toml ``` Changes take effect immediately for all grants that reference this role. Existing sessions are re-evaluated on the next API call. ## Deleting a role Deleting a role removes it from any grants that reference it. This cannot be undone. ```bash theme={null} sf roles delete training-operator ``` ## Example roles ### CI/CD deployer Can create and delete instances, read pools, manage no other resources. ```toml theme={null} api_version = "roles/v1" description = "CI/CD pipeline - deploy and teardown training jobs" [[rules]] effect = "allow" [rules.actions] instance = ["*"] pool = ["read"] secret = ["read"] ssh_key = ["read"] ``` ### Researcher Can use existing infrastructure but not modify pools or access controls. ```toml theme={null} api_version = "roles/v1" description = "Researcher - run training jobs on allocated pools" [[rules]] effect = "allow" [rules.actions] instance = ["read", "write", "list"] ssh_key = ["*"] secret = ["read"] ``` ### Finance View billing data, manage budgets, and view orders. No infrastructure access. ```toml theme={null} api_version = "roles/v1" description = "Finance - view spending and invoices, manage budgets, view orders" [[rules]] effect = "allow" [rules.actions] billing = ["read", "write"] order = ["read"] ```