Access Control & Policies — Primary Skill

Tool availability: some MCP tools named here live in the full toolset profile — if one is not advertised on this connection, tell the user to reconnect the MCP server with ?toolsets=full (or use the cpln CLI fallback). Reads and deletes work on every profile via the generic list_resources / get_resource / delete_resource tools.

A policy targets one resource kind and binds permissions to principals (users, groups, service accounts, workload identities). The common failure is a policy that exists but grants nothing — a wrong targetKind, permission name, or principal link fails with no error — so read the policy back after writing.

The model

A caller is allowed an action when some policy on the resource's kind has a binding that lists that action (or a permission implying it) and names the caller — or a group the caller is in.

Policy anatomy

A policy = one `targetKind` + a target scope + bindings.

kind: policy
name: app-secret-access
targetKind: secret           # exactly one resource kind
targetLinks:                 # OR `target: all` OR `targetQuery:` (pick one)
  - //secret/database-url
bindings:                    # ≤ 50
  - permissions: [reveal, use]
    principalLinks:          # 1–200
      - //gvc/production/identity/app-identity

Limits: bindings ≤ 50; principalLinks 1–200 per binding; targetLinks ≤ 200. origin is read-only — default (yours) or builtin (locked; see Built-ins).

Target scope (pick one): target: all (org-wide roles) · targetLinks (specific resources) · targetQuery (tag query — see query-spec).

Valid target kinds: the targetKind enum accepts all 33 resource kinds, but only the 20 kinds with permission schemas (the ones get_permissions accepts) are meaningful targets: workload, secret, gvc, identity, image, org, policy, group, serviceaccount, user, volumeset, domain, location, ipset, mk8s, cloudaccount, agent, auditctx, quota, task.

Create vs update:

• create_policy builds one binding from addPermissions × (addUsers/addGroups/addServiceAccounts/addIdentities) — providing only one side is an error (a binding needs both). It also requires exactly one target scope (targetAll / targetLinks / targetQuery). For several distinct bindings, use update_policy addBindings.
• update_policy merges bindings (matched by exact permission set — you can't extend a set) but replaces targets (targetLinks wholesale, removeTargetLinks incremental, targetAll — mutually exclusive).

Permissions

`get_permissions` (`kind`) is the source of truth — it returns the kind's exact permission list and its implication map. Confirm names with it before writing a policy; never hand-write them, and don't assume a kind only has create / delete / edit / view / manage.

Two traps that don't need a lookup:

• `manage` implies every permission for a kind — grant it only to true admins.
• Secret values need `reveal`, not `read` — the most common mistake.

Many kinds add non-obvious permissions beyond CRUD — e.g. secret reveal/use, image pull, workload connect/exec.*, serviceaccount addKey, user invite/impersonate, mk8s clusterAdmin — so pull the real set with get_permissions.

Principals

An identity never belongs to a group, so authorize it only with a binding that names its exact link. At runtime the attached identity is the workload's API credential: calls from inside the workload with the injected CPLN_TOKEN against CPLN_ENDPOINT carry exactly the permissions policies grant that identity — nothing more.

Groups

Members are users and service accounts only (≤ 200). Bind policies to groups, not individuals.

• Create / edit: create_group (name, memberLinks, memberQuery, identityMatcher); edit_group (addMemberLinks / removeMemberLinks — read first with get_resource (kind="group")).
• Dynamic: memberQuery matches users by tag query; identityMatcher matches identities by a jmespath/javascript expression.

Service accounts (non-human / CI/CD)

• Key: add_key_to_service_account (serviceAccountName, `keyDescription` required, optional groupName) — auto-creates the SA if missing and returns the key once (save it; lost = revoke + remint). create_service_account makes one with no key.
• Revoke: update_service_account removeKeys: [NAME] (immediate). delete_resource (kind="service_account") revokes all keys.
• CI/CD auth: store the key as the CPLN_TOKEN secret/env var — the CLI uses it ahead of any profile (and works without one); don't pass --token on the command line (it leaks into logs). Full setup: gitops-cicd.

Users (IDP-backed)

• Invite: invite_user_to_org (email, optional groupName).
• Read / remove: get_resource (kind="user") / delete_resource (kind="user") take `identifier` (id or email); list_resources (kind="user") has an email filter. No create_user/update_user.

Built-ins (seeded per org)

• Grant org-admin by adding the principal to `superusers` (or viewers for read-only) — don't recreate admin policies.
• Built-in policies can't be created/edited/deleted; built-in groups can't be deleted, but their membership is editable (you can't remove yourself from superusers).
• Any resource tagged `cpln/protected=true` can't be deleted until untagged.

Common RBAC patterns

create_policy builds these; the cpln apply -f manifest is the policy-as-code equivalent for CI/CD.

• Org admin — add to superusers. Scoped admin — one policy per targetKind with [manage].
• GVC developer — workload [connect, create, delete, edit, exec, view] + secret [create, delete, edit, reveal, use, view] on a developers group.
• Read-only — add to viewers.
• CI/CD SA — workload [create, delete, edit, view] + image [create, pull, view] + secret [use, view] on //serviceaccount/cicd-deployer.
• Workload identity secret access — the anatomy example above; full flow in setup-secret (create identity, bind, attach via spec.identityLink).
• Auditor — policy [view] + auditctx [view] on an auditors group.

Standard flow

1. get_cpln_rules (once per mutating session) and read this skill.
2. Confirm the org (and gvc for identities) — never guess.
3. get_permissions for the kind — confirm permission names.
4. Read current state: list_resources (kind="policy") / get_resource (kind="policy") (+ get_resource kind="group" / kind="service_account").
5. Smallest change; if destructive, confirm blast radius.
6. create_policy / update_policy (+ group / SA / user tools).
7. Verify: read the policy back; confirm the bindings and target resolved.

Quick reference — MCP tools

CLI fallback (read the cpln skill first; verify with cpln <resource> --help): policy-as-code in CI/CD (CPLN_TOKEN + cpln apply -f), cpln RESOURCE permissions to list a kind's permissions, cpln policy access-report NAME to audit a policy.

Related skills

Documentation

• Access Control Concepts
• Policy Reference