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

# List roles

`GET /roles`

Get a list of all available roles with optional provider filtering and search

## Query parameters

- `provider` string
- `q` string
- `limit` integer

## Response `200`

List of roles

- GithubComThandIoAgentInternalModelsRolesResponse
  - `meta` GithubComThandIoAgentInternalModelsResponseMeta
    - `page` integer
    - `page_size` integer
    - `total` integer
    - `total_pages` integer
  - `roles` object[]
    - `_id` string
    - `_reason` string
    - `_score` number
    - `_source` GithubComThandIoAgentInternalModelsRoleResponse
      - `authenticators` string[] — All the auth providers that the role can use. If empty then any provider can be used
      - `composite` boolean — Whether this role is a composite role (i.e., aggregates other roles)
      - `description` string
      - `enabled` boolean — By default enable the role
      - `identifier` string — To be set by the system
      - `inherits` string[] — roles to inherit from or provider specific roles/policies etc
      - `name` string, required
      - `permissions` GithubComThandIoAgentInternalModelsRolePermissions
        - `allow` ModelsStatement[]
          - `conditions` object — Conditions contains optional provider-specific conditions. WARNING: Conditions are PRESERVED but NOT EVALUATED by this system. Enforcement is delegated to the target provider's IAM system. Examples: {"IpAddress": {"aws:SourceIp": "10.0.0.0/8"}} for AWS
          - `operations` string[] — Operations contains provider-specific actions/permissions. Examples: ["s3:GetObject", "s3:PutObject"] for AWS, ["storage.buckets.get"] for GCP
          - `targets` string[] — Targets contains provider-specific resource identifiers. Examples: ["arn:aws:s3:::my-bucket/*"] for AWS, ["projects/my-project/buckets/my-bucket"] for GCP
        - `deny` ModelsStatement[]
          - `conditions` object — Conditions contains optional provider-specific conditions. WARNING: Conditions are PRESERVED but NOT EVALUATED by this system. Enforcement is delegated to the target provider's IAM system. Examples: {"IpAddress": {"aws:SourceIp": "10.0.0.0/8"}} for AWS
          - `operations` string[] — Operations contains provider-specific actions/permissions. Examples: ["s3:GetObject", "s3:PutObject"] for AWS, ["storage.buckets.get"] for GCP
          - `targets` string[] — Targets contains provider-specific resource identifiers. Examples: ["arn:aws:s3:::my-bucket/*"] for AWS, ["projects/my-project/buckets/my-bucket"] for GCP
      - `providers` string[] — providers that can assign this role
      - `scopes` GithubComThandIoAgentInternalModelsRoleScopes
        - `allow` ModelsScopeIdentities
          - `domains` string[]
          - `groups` string[]
          - `users` string[]
        - `deny` ModelsScopeIdentities
          - `domains` string[]
          - `groups` string[]
          - `users` string[]
      - `version` VersionVersion
      - `workflows` string[] — The workflows to execute
  - `version` VersionVersion

## Other responses

- `401` — Unauthorized

---

[API](https://skmtc.net/thand-io/apis/thand-agent-api.md) · [All operations](https://skmtc.net/thand-io/apis/thand-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/thand-io/thand-agent-api/revisions/62befb178368/schema)