> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/rbac-policies-api.md).

# RBAC Policies API

Manage access policies, data scopes, assignments, and policy revisions.

Manage access policies, data scopes, assignments, and policy revisions.

## Authentication

Admin permissions are required to create, update, delete, or apply policies. Reading policies and their audit trails requires authenticated access. Set `GC_API_KEY` to an API key with the required permissions and `GC_BACKEND_ID` to the backend ID. Every example sends both headers. For self-hosted deployments, replace `https://api.groundcover.com` with your API URL.

## Endpoints

| Method | Endpoint                           | Operation                        | Permissions          |
| ------ | ---------------------------------- | -------------------------------- | -------------------- |
| POST   | `/api/rbac/policy/create`          | Create                           | Admin                |
| GET    | `/api/rbac/policies/list`          | List policies with entity counts | Authenticated access |
| GET    | `/api/rbac/policy/{id}`            | Get policy                       | Authenticated access |
| PUT    | `/api/rbac/policy/{id}`            | Update policy                    | Admin                |
| DELETE | `/api/rbac/policy/{id}`            | Delete policy                    | Admin                |
| POST   | `/api/rbac/policy/apply`           | Assign policies to users         | Admin                |
| GET    | `/api/rbac/policy/{id}/auditTrail` | Retrieve revisions               | Authenticated access |

## Create a policy

`name` and a nonempty `role` map are required. Role keys are `read`, `write`, or `admin`; the example uses `{"read":""}`. Optional fields are `description`, `claimRole`, `dataScope`, and `sensitiveAccess` (default `false`).

`dataScope` supports either a shared `simple` filter group or signal-specific `advanced` groups for `logs`, `traces`, `events`, `metrics`, and `workloads`. These are structured filter groups, not gcQL strings. Omitting a data scope does not restrict data to a particular cluster. The example creates an unrestricted Reader policy; use a scoped policy when access should be limited.

```bash
curl --request POST \
  --url "https://api.groundcover.com/api/rbac/policy/create" \
  --header "Authorization: Bearer $GC_API_KEY" \
  --header "X-Backend-Id: $GC_BACKEND_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "automation-reader",
  "description": "Read access for automation",
  "role": {
    "read": ""
  },
  "sensitiveAccess": false
}'
```

HTTP `201` returns the policy, including `uuid`, `revisionNumber`, `role`, `dataScope`, `readOnly`, and audit timestamps. `sensitiveAccess` controls access to sensitive attributes independently of the role.

## Scope access to an environment

To restrict a policy to the `staging` environment, include the following `dataScope` in its create or update body:

```json
{
  "simple": {
    "operator": "and",
    "conditions": [
      {
        "key": "environment",
        "origin": "root",
        "type": "string",
        "filters": [
          {
            "op": "match",
            "value": "staging"
          }
        ]
      }
    ]
  }
}
```

The same filter group can be placed under `dataScope.advanced.logs` or another supported signal to set signal-specific scope. Preserve all desired signal scopes when updating.

## List, read, and retrieve history

```bash
curl --request GET \
  --url "https://api.groundcover.com/api/rbac/policies/list" \
  --header "Authorization: Bearer $GC_API_KEY" \
  --header "X-Backend-Id: $GC_BACKEND_ID"
```

```bash
curl --request GET \
  --url "https://api.groundcover.com/api/rbac/policy/<POLICY_UUID>" \
  --header "Authorization: Bearer $GC_API_KEY" \
  --header "X-Backend-Id: $GC_BACKEND_ID"
```

```bash
curl --request GET \
  --url "https://api.groundcover.com/api/rbac/policy/<POLICY_UUID>/auditTrail" \
  --header "Authorization: Bearer $GC_API_KEY" \
  --header "X-Backend-Id: $GC_BACKEND_ID"
```

List and history return arrays; get returns one policy. List also includes `entityCount`.

## Update

Read the latest policy first. Send `name`, `role`, the desired optional settings, and its `revisionNumber` as `currentRevision`. Preserve any existing `dataScope`, `claimRole`, and `sensitiveAccess` values you intend to retain. This is a full configuration update, not a JSON Patch.

```bash
curl --request PUT \
  --url "https://api.groundcover.com/api/rbac/policy/<POLICY_UUID>" \
  --header "Authorization: Bearer $GC_API_KEY" \
  --header "X-Backend-Id: $GC_BACKEND_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "automation-reader",
  "description": "Updated description",
  "role": {
    "read": ""
  },
  "sensitiveAccess": false,
  "currentRevision": 1
}'
```

Replace `1` with the revision returned by get. Success returns HTTP `202` and the updated policy. Reload before retrying a stale revision.

## Apply to users

Both `policyUUIDs` and `emails` must be nonempty arrays. `override: true` replaces the users' assignments; `false` appends. Use the [Service Accounts API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/service-accounts-api.md) to assign policies to service accounts.

```bash
curl --request POST \
  --url "https://api.groundcover.com/api/rbac/policy/apply" \
  --header "Authorization: Bearer $GC_API_KEY" \
  --header "X-Backend-Id: $GC_BACKEND_ID" \
  --header "Content-Type: application/json" \
  --data '{
  "policyUUIDs": [
    "<POLICY_UUID>"
  ],
  "emails": [
    "reader@example.com"
  ],
  "override": true
}'
```

Success returns HTTP `200` with no body.

## Delete

```bash
curl --request DELETE \
  --url "https://api.groundcover.com/api/rbac/policy/<POLICY_UUID>" \
  --header "Authorization: Bearer $GC_API_KEY" \
  --header "X-Backend-Id: $GC_BACKEND_ID"
```

Success returns HTTP `200` with no body. A policy used as the tenant default cannot be deleted until the [default policy](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/tenant-settings-api.md) is changed. System-managed policies may be read-only.

For advanced data scopes, `index_tier` filters are supported only in the `logs` and `traces` groups, as root string conditions; they cannot be used in a `simple` scope or the other signal groups.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/rbac-policies-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
