> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Policies

> Create and manage RBAC access policies in Essal Guard to control resource-level permissions across all apps.

Essal Guard provides **policy-based access control** that sits on top of the role system. Policies allow you to define fine-grained rules — allowing or denying specific actions on specific resources — beyond what roles alone can express.

## How Policies Work

Guard evaluates every API request in the following order:

1. **Explicit Deny**: If any matching policy explicitly denies the action, it is blocked regardless of roles
2. **Role Allow**: If the user's roles grant the action, it is permitted
3. **Policy Allow**: If a policy explicitly allows the action, it is permitted
4. **Default Deny**: All other requests are denied

## Creating a Policy

```bash theme={null}
POST /v1/guard/policies
{
  "name": "Engineering Docs — Read Only for Contractors",
  "description": "Contractors can read but not edit Engineering documents.",
  "effect": "deny",
  "principals": [
    { "type": "group", "id": "grp_01HXYZ_CONTRACTORS" }
  ],
  "resources": [
    { "type": "office.document", "tag": "engineering" }
  ],
  "actions": ["office:write", "office:delete"]
}
```

```json theme={null}
{
  "id": "pol_01HXYZPOL1",
  "name": "Engineering Docs — Read Only for Contractors",
  "status": "active",
  "created_at": "2026-07-08T11:00:00Z"
}
```

## Policy Components

| Component    | Description                                                          |
| ------------ | -------------------------------------------------------------------- |
| `principals` | Who the policy applies to: users, groups, or service accounts        |
| `resources`  | What the policy applies to: specific IDs, types, or tagged resources |
| `actions`    | The API scopes being allowed or denied                               |
| `effect`     | Either `allow` or `deny`                                             |
| `conditions` | Optional: time-based, IP-based, or MFA-based conditions              |

## Conditional Policies

Add conditions to make policies context-aware:

```bash theme={null}
POST /v1/guard/policies
{
  "name": "Guard Logs — Business Hours Only",
  "effect": "allow",
  "principals": [{ "type": "role", "value": "guard:auditor" }],
  "resources": [{ "type": "guard.audit_log" }],
  "actions": ["guard:read"],
  "conditions": {
    "time": {
      "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "hours": { "from": "08:00", "to": "18:00", "timezone": "Europe/London" }
    }
  }
}
```

## Testing a Policy

Before activating a policy, test it against a hypothetical request:

```bash theme={null}
POST /v1/guard/policies/pol_01HXYZPOL1/evaluate
{
  "principal": { "type": "group", "id": "grp_01HXYZ_CONTRACTORS" },
  "resource": { "type": "office.document", "id": "doc_01HXYZABC" },
  "action": "office:write"
}
```

```json theme={null}
{ "result": "deny", "matched_policy": "pol_01HXYZPOL1" }
```

<Warning>
  Test policies thoroughly before activation. A misconfigured deny policy can lock users out of resources. Use `"status": "inactive"` to draft policies before enabling them.
</Warning>