Atomically replace all access grants for a rule with the grants you send. Any existing grant not present in the request is removed. Requires modify access to the rule.

## Path parameters

**`rule_id`** string required

Rule ID (prefixed with `rule_`).

## Request body

The body is a JSON array of grant objects. Each object has:

- **`target_type`** string (required) — Scope of the grant. Values: `user` (one user), `organization` (all members), `department`, or `all`.
- **`target_id`** string (required) — ID of the target entity (user ID, org ID, or department ID). Use `*` when `target_type` is `all`.
- **`access_level`** string (required) — `view` (read-only visibility), `use` (can invoke/attach the rule), or `modify` (full control).


## Returns

Returns the resulting list of access grants.

Request

```bash cURL
curl -X PUT "https://api.aitronos.com/v1/rules/rule_abc123/permissions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{ "target_type": "user", "target_id": "usr_abc", "access_level": "use" }]'
```


```python Python SDK
# A first-class SDK method for this endpoint is coming soon.
# In the meantime, call the endpoint directly with the SDK's HTTP client:
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")
response = client._client_wrapper.httpx_client.request(
    "rules/rule_abc123/permissions",
    method="PUT",
    json=[{"target_type": "user", "target_id": "usr_abc", "access_level": "use"}],
)
print(response.json())
```


```python Python
import os, requests

response = requests.put(
    "https://api.aitronos.com/v1/rules/rule_abc123/permissions",
    headers={
        "Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}",
        "Content-Type": "application/json",
    },
    json=[{"target_type": "user", "target_id": "usr_abc", "access_level": "use"}],
)
print(response.json())
```


```javascript JavaScript
await fetch("https://api.aitronos.com/v1/rules/rule_abc123/permissions", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    { target_type: "user", target_id: "usr_abc", access_level: "use" },
  ]),
});
```

Response

```json 200 OK
{
  "grants": [
    {
      "id": "grant_abc123",
      "target_type": "user",
      "target_id": "usr_abc",
      "access_level": "use",
      "granted_by": "usr_owner",
      "granted_at": "2026-04-15T10:00:00Z"
    }
  ]
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You do not have permission to perform this action.",
    "system_message": "Insufficient permissions for this operation",
    "type": "authorization_error",
    "status": 403,
    "details": { "rule_id": "rule_abc123" },
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-04-15T10:00:00Z"
  }
}
```

## Related Resources

- [List rule permissions](/docs/api-reference/rules/permissions-list)
- [Grant rule permission](/docs/api-reference/rules/permissions-grant)
- [Revoke rule permission](/docs/api-reference/rules/permissions-revoke)