access-control

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

Layer	Scope	Controls
Billing-account roles	account-wide (set on the billing account, separate from org policies)	billing_admin, billing_viewer, org_creator — none grant org-resource access
Org policies	per resource kind	all day-to-day access

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

Type	Link
User	//user/EMAIL
Group (preferred)	//group/NAME
Service account	//serviceaccount/NAME
Workload identity	//gvc/GVC/identity/NAME (GVC-scoped — never //identity/NAME)

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)

Resource	Name	Grants
Group	superusers	manage on every kind (creator auto-added)
Group	viewers	view on every kind
Service account	controlplane	platform-internal — off-limits
Policies	superusers-KIND / viewers-KIND	origin: builtin, target: all

• 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

Tool	Purpose	Key params
mcp__cpln__get_permissions	Permissions + implications for a kind	kind
mcp__cpln__list_resources (kind="policy") / get_resource (kind="policy")	List / read policies	name
mcp__cpln__create_policy	Create a policy	name, targetKind, targetAll/targetLinks/targetQuery, addPermissions, addUsers/addGroups/addServiceAccounts/addIdentities
mcp__cpln__update_policy	Update metadata, targets, bindings	name, addBindings/removeBindings, targetLinks/removeTargetLinks/targetAll, targetQuery
mcp__cpln__delete_resource (kind="policy")	Delete a policy (destructive)	name
mcp__cpln__list_resources (kind="group") / get_resource (kind="group")	List / read groups	name
mcp__cpln__create_group	Create a group	name, memberLinks, memberQuery, identityMatcher
mcp__cpln__edit_group	Add/remove members, update meta	name, addMemberLinks, removeMemberLinks
mcp__cpln__delete_resource (kind="group")	Delete a group (destructive)	name
mcp__cpln__list_resources (kind="service_account") / get_resource (kind="service_account")	List / read SAs (key metadata only)	name
mcp__cpln__create_service_account	Create an SA (no key)	name, description
mcp__cpln__add_key_to_service_account	Mint a key (auto-creates SA)	serviceAccountName, keyDescription, groupName
mcp__cpln__update_service_account	Update meta / revoke keys	name, removeKeys
mcp__cpln__delete_resource (kind="service_account")	Delete an SA (revokes all keys)	name
mcp__cpln__list_resources (kind="user") / get_resource (kind="user")	List / read users	email / identifier
mcp__cpln__invite_user_to_org	Invite a user by email	email, groupName
mcp__cpln__delete_resource (kind="user")	Remove a user (destructive)	identifier

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

Need	Skill
Query language for targetQuery / memberQuery	query-spec
Org creation, billing, profiles, SSO	org-management
Audit trail of policy / access changes	audit-compliance
Full workload secret-access flow	setup-secret
Credential-free cloud access (AWS / GCP / Azure / NGS)	setup-cloud-access
Workload identities, private-network connectivity	native-networking

Documentation

• Access Control Concepts
• Policy Reference