# Policies

A policy is the fundamental unit of access control in Aritma IAM. It binds a subject to an action on a specific scope, granting that subject permission to perform that action on that resource.

## The policy model

Every policy has exactly three fields:

| Field | Description | Example |
|  --- | --- | --- |
| `subject` | Who is being granted access (user, client, or group subject ID) | `user-550e8400-e29b-41d4-a716-446655440000` |
| `action` | What they are allowed to do (dot-notation action string) | `banking.manage` |
| `scope` | Which resource the permission applies to (a URI) | `/subscriptions/123/resource-groups/00000000-0000-0000-0000-000000000000` |


### Example

This policy grants Alice full banking management on a specific subscription:


```json
{
  "subject": "user-550e8400-e29b-41d4-a716-446655440000",
  "action": "banking.manage",
  "scope": "/subscriptions/123/resource-groups/00000000-0000-0000-0000-000000000000"
}
```

Because `banking.manage` is a parent action, Alice also implicitly has all actions nested under it - such as `banking.consents.create` and `banking.ais.read`.

See the Actions Hierarchy page for the full tree of available actions.

### Subjects can be groups

If you want to grant the same permission to multiple users at once, create the policy with a group's `subjectId` as the subject. All current and future members of that group will inherit the policy automatically.


```json
{
  "subject": "group-7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "action": "banking.ais.read",
  "scope": "/subscriptions/123/resource-groups/00000000-0000-0000-0000-000000000000"
}
```

## Create a policy

**Request body:**


```json
{
  "subject": "user-550e8400-e29b-41d4-a716-446655440000",
  "action": "banking.manage",
  "scope": "/subscriptions/123/resource-groups/00000000-0000-0000-0000-000000000000"
}
```

**Response:**


```json
{
  "subject": "user-550e8400-e29b-41d4-a716-446655440000",
  "action": "banking.manage",
  "scope": "/subscriptions/123/resource-groups/00000000-0000-0000-0000-000000000000",
  "tenant": "tenant_xyz"
}
```

Idempotency
Creating the same policy twice returns `409 Conflict`. Check for an existing policy before creating if your code may run more than once.

## Query policies

Find policies matching a filter. You can filter by subject, action, scope, or any combination:

Example - find all policies for a specific subject on a given subscription:

### Query parameters

| Parameter | Description |
|  --- | --- |
| `subject` | Filters results to policies belonging to this subject identifier |
| `scope` | Filters results to policies on this scope |
| `action` | Filters results to policies granting this action |
| `includeDerived` | If `true`, includes policies with a derived (child) scope |
| `includeInherited` | If `true`, includes policies with a parent scope |
| `pageSize` | Number of items to return per page. Clamped between 10 and 200 |
| `cursor` | Opaque cursor returned from a previous response. Pass this to retrieve the next page |


### Pagination

`FindPolicies` uses cursor-based pagination. Each response includes a `cursor` field. Pass that value as `cursor` in your next request to retrieve the following page. When `cursor` is `null`, there are no more results.


```json
{
  "policies": [...],
  "cursor": "eyJhbGciOiJub25lIn0"
}
```

## Delete a policy

The request body must match the policy exactly (same subject, action, and scope):


```json
{
  "subject": "user-550e8400-e29b-41d4-a716-446655440000",
  "action": "banking.manage",
  "scope": "/subscriptions/123/resource-groups/00000000-0000-0000-0000-000000000000"
}
```

## Common patterns

### Grant a user access to a new subscription

### Grant read-only access

Use a more specific action to limit what a subject can do:

### Revoke all access for a user

First, query all policies for that subject, then delete each one: