---
title: "Update role"
method: PUT
path: "/preview/v2/roles/{id}"
tags: ["Roles"]
---

# Update role

`PUT /preview/v2/roles/{id}`

> ⚠️ This endpoint is in [public preview](/preview/roadmap).

Update a role's name and/or policy.

## Path parameters

- `id` string, required — A resource path like 'sfc:role:acme:my-role' _or_ an ID. Resource paths are human-readable but not stable - they change when resources are renamed or moved. IDs are stable and permanent.

## Request body

- SfcApiUpdateRoleRequest
  - `name` string
  - `policy` SfcApiPolicy — A parsed permission policy. Policies contain a list of rules. When evaluating whether an action is permitted, all matching rules are combined by unioning their capabilities. If no rule matches, the action is denied by default.
    - `api_version` 'roles/v1', required — Validated API version string. Currently only `"roles/v1"` is accepted.
    - `description` string, required
    - `rules` SfcApiRule[]
      - `effect` 'allow' | 'require_approval' | 'approve_approval', required — The effect of a rule on a matched action. Effects form a hierarchy for the approval system: - `Allow` is the union of `RequireApproval` and `ApproveApproval`: the user can perform the action directly, request approvals, and approve others' requests. - `RequireApproval` means the user can request approval but cannot perform the action directly or approve others' requests. - `ApproveApproval` means the user can approve others' approval requests but cannot perform the action directly or create approval requests.
      - `actions` SfcApiActionsMap, required — A map from resource to verbs. Serializes as e.g. `{ "node": ["read", "write"], "capacity": ["*"] }`. Uses `BTreeMap` for deterministic key ordering.

## Response `200`

Role updated.

- SfcApiRoleResponse
  - `id` string, required
  - `resource_path` string, required — A resource path for a role resource. Format: sfc:role:<account>:<name>.
  - `owner` string, required
  - `name` string, required
  - `object` 'role', required
  - `role_type` 'built_in' | 'custom', required
  - `policy` SfcApiPolicy, required — A parsed permission policy. Policies contain a list of rules. When evaluating whether an action is permitted, all matching rules are combined by unioning their capabilities. If no rule matches, the action is denied by default.
    - `api_version` 'roles/v1', required — Validated API version string. Currently only `"roles/v1"` is accepted.
    - `description` string, required
    - `rules` SfcApiRule[]
      - `effect` 'allow' | 'require_approval' | 'approve_approval', required — The effect of a rule on a matched action. Effects form a hierarchy for the approval system: - `Allow` is the union of `RequireApproval` and `ApproveApproval`: the user can perform the action directly, request approvals, and approve others' requests. - `RequireApproval` means the user can request approval but cannot perform the action directly or approve others' requests. - `ApproveApproval` means the user can approve others' approval requests but cannot perform the action directly or create approval requests.
      - `actions` SfcApiActionsMap, required — A map from resource to verbs. Serializes as e.g. `{ "node": ["read", "write"], "capacity": ["*"] }`. Uses `BTreeMap` for deterministic key ordering.
  - `created_at` integer, required — Unix timestamp.
  - `updated_at` integer, required — Unix timestamp.

## Other responses

- `400` — Invalid policy.
- `401` — Unauthorized.
- `403` — Forbidden.
- `404` — Role not found.
- `500` — Internal server error.

---

[API](https://skmtc.net/sfcompute/apis/san-francisco-compute-documentation.md) · [All operations](https://skmtc.net/sfcompute/apis/san-francisco-compute-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sfcompute/san-francisco-compute-documentation/revisions/93dd7661e9bb/schema)