> ## 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.

# Grants

> Assign roles to users and tokens

<Warning>
  This feature is in [public preview](/preview/roadmap).
</Warning>

A grant assigns a role to a user or token within a workspace or across the entire organization.

## Granting access to a user

Grant a role directly to a user by their email.

```bash theme={null}
sf grants create \
  --workspace production \
  --user alice@acme.co \
  --role admin
```

Alice now has admin access to the `production` workspace.

## Organization-wide grants

Use `--org` to grant a role across all workspaces in the organization.

```bash theme={null}
sf grants create \
  --org \
  --user alice@acme.co \
  --role admin
```

Alice now has admin access to every workspace in the organization.

## Listing grants

List all grants in the organization:

```bash theme={null}
sf grants list
```

```
ID                          WORKSPACE     ROLE                TYPE    PRINCIPAL        CREATED
grnt_k3RnX9vLm7Qp2Yw5Jd     (Org-wide)    admin               user    alice@acme.co    Feb 4, 2025
grnt_8KvQ3mWxYpRtZn6Hb2     production    training-operator   user    bob@acme.co      Feb 3, 2025
grnt_5DhP2nLqWmKjXc9Rv0     production    viewer              token   tokn_5DhP2nLqWmK Feb 1, 2025
```

Filter by workspace or by user:

```bash theme={null}
sf grants list --workspace production
sf grants list --user alice@acme.co
```

## Removing a grant

Remove a workspace-scoped grant:

```bash theme={null}
sf grants delete \
  --workspace production \
  --user bob@acme.co \
  --role training-operator
```

Remove an organization-wide grant:

```bash theme={null}
sf grants delete \
  --org \
  --user alice@acme.co \
  --role admin
```

## Multiple grants

A user or token can have multiple grants. Permissions are combined (union of all roles).

```bash theme={null}
sf grants create --org --user bob@acme.co --role viewer
sf grants create --workspace production --user bob@acme.co --role training-operator
```

Bob has `viewer` access organization-wide and `training-operator` access in `production`.

## Token grants

Tokens can also be granted roles. This is useful for CI/CD pipelines and automation.

```bash theme={null}
sf grants create \
  --workspace production \
  --token ci-deploy \
  --role training-operator
```

Alternatively, assign a role when creating the token. `sf tokens create` creates one grant per
role with no workspace scope, so these grants apply organization-wide. To scope a token's role to a
single workspace, create the grant explicitly with `sf grants create --token` and `--workspace`.
See [Tokens](/preview/tokens).

```bash theme={null}
sf tokens create --name ci-deploy --role training-operator
```

## How grants interact with roles

Grants bind users or tokens to roles. Roles define what actions are allowed. The evaluation order
is:

1. Collect all grants for the user or token on the target workspace (including organization-wide
   grants).
2. Collect all rules from all matched roles.
3. If any rule allows the action, allow.
4. Otherwise, deny.