---
title: "List roles"
method: GET
path: "/preview/v2/roles"
tags: ["Roles"]
---

# List roles

`GET /preview/v2/roles`

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

List all role definitions. Built-in roles appear first, followed by custom roles sorted by creation date (newest first).

## Query parameters

- `id` SfcApiResourcePathOrIdRoleId[]

## Response `200`

List of roles.

- SfcApiListRolesResponse
  - `object` 'list', required
  - `data` SfcApiRoleResponse[], required
    - `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

- `401` — Unauthorized.
- `403` — Forbidden.
- `422` — Validation error.
- `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)