Site: Planekeeper Docs — Monitor software versions across your stack. Planekeeper tracks releases, gathers version data, and alerts on drift.
Section: Reference > IAM Policy Documents
Source: https://docs.planekeeper.com/reference/iam-policies/
Title: IAM Policy Documents
Author: Planekeeper
Description: Reference guide for IAM-style policy documents used in Planekeeper role management.
Word count: 490
Reading time: 3 min

Contents:
- [Policy Document Format](#policy-document-format)
- [Actions](#actions)
  - [Available Resources](#available-resources)
  - [Wildcards](#wildcards)
- [Resource ARN](#resource-arn)
- [Deny Statements](#deny-statements)
  - [Example: Admin without role management](#example-admin-without-role-management)
- [Common Templates](#common-templates)
  - [Read-only (Viewer)](#read-only-viewer)
  - [Operator (run jobs, acknowledge alerts)](#operator-run-jobs-acknowledge-alerts)
  - [Full access except API keys and roles](#full-access-except-api-keys-and-roles)

***

# IAM Policy Documents


Custom roles in Planekeeper use AWS IAM-style JSON policy documents to define permissions. This page explains the format, wildcards, deny behavior, and org scoping.

## Policy Document Format

A policy document is a JSON object with a `Statement` array:

```json
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["gather-jobs:list", "gather-jobs:get", "releases:*"],
      "Resource": "planekeeper:org:*:*:*"
    }
  ]
}
```

Each statement has three fields:

| Field | Type | Description |
|-------|------|-------------|
| `Effect` | string | `Allow` or `Deny` |
| `Action` | string[] | Array of `resource:action` patterns |
| `Resource` | string | ARN-style resource identifier |

## Actions

Actions use the format `resource:action`. For example:

- `gather-jobs:list` -- list gather jobs
- `alerts:acknowledge` -- acknowledge an alert
- `roles:create` -- create a custom role

### Available Resources

| Resource | Actions |
|----------|---------|
| `agents` | list |
| `alert-configs` | list, create, get, update, delete, toggle |
| `alerts` | list, get, get-summary, list-resolved, acknowledge, unacknowledge, resolve, bulk-acknowledge, list-actions, get-deliveries |
| `api-keys` | list, create, get, update, toggle, deactivate |
| `dropdowns` | list |
| `feedback` | create |
| `gather-jobs` | list, create, get, update, delete, run, clear-releases, get-summary |
| `helm-sync-jobs` | list, create, get, update, delete, run, list-charts |
| `monitoring-rules` | list, create, get, update, delete, toggle, evaluate |
| `notification-channels` | list, create, get, update, delete, toggle, test, validate, get-stats |
| `notification-deliveries` | list, list-dead, retry |
| `notification-rules` | list, create, get, update, delete, toggle, simulate, get-stats |
| `notification-settings` | get, update |
| `notification-templates` | list, update, delete, preview |
| `releases` | list, get, get-summary |
| `roles` | list, create, get, update, delete, assign |
| `scrape-jobs` | list, create, get, update, delete, run, set-version, get-versions, get-summary |
| `settings` | list, get-effective, list-overrides, update-override, delete-override |
| `submission-logs` | list |
| `versions` | list |

### Wildcards

Use `*` as a wildcard in either the resource or action position:

| Pattern | Meaning |
|---------|---------|
| `gather-jobs:*` | All actions on gather jobs |
| `*:list` | List action on all resources |
| `*:*` | Full access to everything |

## Resource ARN

The `Resource` field uses an ARN (Amazon Resource Name) format:

```
planekeeper:org:<org_id>:<resource>:<instance>
```

| Segment | Description |
|---------|-------------|
| `planekeeper` | Fixed prefix |
| `org` | Fixed segment |
| `<org_id>` | Organization ID (number) or `*` for all orgs |
| `<resource>` | Resource type (e.g., `gather-jobs`) or `*` |
| `<instance>` | Resource instance (`*` for all) |

> **info:** 
**Org ID is server-controlled**

When you create or edit a role, the org ID in the Resource ARN is automatically set from your session. You cannot specify another organization's ID -- the server always stamps your own org. System roles use `org:*` to indicate they apply across all organizations.


## Deny Statements

Use `Effect: "Deny"` to explicitly block specific actions. **Deny always wins** -- if any statement denies an action, the action is blocked even if another statement allows it.

### Example: Admin without role management

```json
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["*:*"],
      "Resource": "planekeeper:org:*:*:*"
    },
    {
      "Effect": "Deny",
      "Action": ["roles:*"],
      "Resource": "planekeeper:org:*:roles:*"
    }
  ]
}
```

This grants full access to everything except role management.

## Common Templates

### Read-only (Viewer)

```json
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["*:list", "*:get", "*:get-summary", "*:get-stats"],
      "Resource": "planekeeper:org:*:*:*"
    }
  ]
}
```

### Operator (run jobs, acknowledge alerts)

```json
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "*:list", "*:get", "*:get-summary",
        "gather-jobs:run",
        "scrape-jobs:run",
        "helm-sync-jobs:run",
        "alerts:acknowledge", "alerts:unacknowledge", "alerts:resolve"
      ],
      "Resource": "planekeeper:org:*:*:*"
    }
  ]
}
```

### Full access except API keys and roles

```json
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["*:*"],
      "Resource": "planekeeper:org:*:*:*"
    },
    {
      "Effect": "Deny",
      "Action": ["api-keys:*", "roles:*"],
      "Resource": "planekeeper:org:*:*:*"
    }
  ]
}
```


---

## Related

- Next: [Parser types](https://docs.planekeeper.com/reference/parser-types/page.md) — Reference for the four parser types — YQ, JQ, Regex, and Manual — used by scrape jobs to extract or set version strings.
- Section: [Reference](https://docs.planekeeper.com/reference/index.md)