IAM Policy Documents

Reference guide for IAM-style policy documents used in Planekeeper role management.

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:

{
  "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

{
  "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)

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

Operator (run jobs, acknowledge alerts)

{
  "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

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