access-control

name	access-control
description	Primary skill for access control, policies, and RBAC on Control Plane. Use when the user asks about permissions, policies, service accounts, user access, group membership, bindings, who can do what, least-privilege, or IAM.

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