> ## 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.

# Policies

> API reference for Essal Guard access policies — create, evaluate, test, activate, and delete policies.

## List Policies

`GET /v1/guard/policies`

**Query Parameters**

| Parameter | Type | Description          |
| --------- | ---- | -------------------- |
| `status`  | enum | `active`, `inactive` |
| `effect`  | enum | `allow`, `deny`      |

***

## Get a Policy

`GET /v1/guard/policies/{id}`

***

## Create a Policy

`POST /v1/guard/policies`

```json theme={null}
{
  "name": "Contractors — Office Read Only",
  "effect": "deny",
  "principals": [{ "type": "group", "id": "grp_01HXYZ_CONTRACTORS" }],
  "resources": [{ "type": "office.document", "tag": "engineering" }],
  "actions": ["office:write", "office:delete"]
}
```

**Response** — `201 Created`

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

Policies are created in `inactive` status. Activate explicitly.

***

## Activate / Deactivate a Policy

`PATCH /v1/guard/policies/{id}`

```json theme={null}
{ "status": "active" }
```

***

## Evaluate a Policy

`POST /v1/guard/policies/{id}/evaluate`

Test how a policy would respond to a hypothetical request:

```json theme={null}
{
  "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" }
```

***

## Delete a Policy

`DELETE /v1/guard/policies/{id}`

Policies can only be deleted when in `inactive` status.