> ## Documentation Index
> Fetch the complete documentation index at: https://controlplanecorporation-majid-docs-content-expansion.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Access Control

> Two independent systems, where billing roles decide who pays and who may create orgs, and org policies decide who can do what to which resources.

<Tabs>
  <Tab title="Organization">
    Inside an [org](/concepts/org), nothing is permitted until a [policy](/reference/policy) says so. Policies grant permissions to principals through bindings, and go as narrow as one [service account](/reference/serviceaccount) holding `edit` on one [workload](/concepts/workload), so a principal can hold only the access its job needs.

    The creator of the org, and anyone invited as an org admin at creation, joins the built-in [`superusers` group](/reference/group#built-in-groups) and holds every permission on every resource.
  </Tab>

  <Tab title="Billing Account">
    [Billing accounts](/concepts/billing) have three roles, assigned when you add someone as a billing user:

    | Role             | Description                                                                                            |
    | ---------------- | ------------------------------------------------------------------------------------------------------ |
    | `billing_admin`  | Manages the account details, its billing users, payment methods, and the spend alert, and creates orgs |
    | `billing_viewer` | Reads the account details, its `Cost & Usage`, and its invoices                                        |
    | `org_creator`    | Creates orgs that bill to the account                                                                  |

    Billing account roles are independent of org-level policies. A `billing_admin` can manage invoices and see which orgs the account pays for, but holds no implicit permissions on the resources inside them.

    Membership is separate too. Being added to the account does not make someone a member of any org.

    <Card title="Billing Account" icon="credit-card" href="/concepts/billing" horizontal>
      Payment methods, invoices, what each org costs, and the monthly spend alert.
    </Card>

    ***
  </Tab>
</Tabs>

## What a Policy Contains

A policy joins three things.

| Piece        | What it is                                                              | Choices                                                                                                                                                |
| ------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Target kind  | The one [resource kind](/concepts/resource-model) the policy applies to | Exactly one, fixed for the life of the policy, for instance a [workload](/concepts/workload), a [secret](/reference/secret), or a [GVC](/concepts/gvc) |
| Target items | Which resources of that kind it covers                                  | Every item of the kind, a list of named ones, or whatever a [query](/core/query) on tags, properties, or relations matches                             |
| Bindings     | Permissions paired with the principals that receive them                | Several per policy, each with its own permission set and any mix of the four principal kinds below                                                     |

<img src="https://mintcdn.com/controlplanecorporation-majid-docs-content-expansion/rUryc3z9dDsnWr_V/images/concepts/policy-sentence.svg?fit=max&auto=format&n=rUryc3z9dDsnWr_V&q=85&s=b5745574ba562b03d5f65a29d40c78f7" alt="A policy is one sentence with three parts. WHO, shown as the service account ci-deploy, can do WHAT, shown as the permission edit, on WHICH resource, shown as the workload my-app. Underneath each part, the alternatives: WHO can be a user, a group, a service account, or a workload's identity; WHAT can be view, edit, manage, or another permission depending on the resource kind; WHICH can be a workload, a secret, a GVC, or any other resource kind. You write all three in one policy, and nothing is allowed unless a policy grants it." style={{maxWidth:'720px',width:'100%',margin:'1.75rem auto',display:'block'}} width="720" height="216" data-path="images/concepts/policy-sentence.svg" />

## Principals

A principal is what a policy grants permissions to. Control Plane has four kinds, each belonging to one org.

<CardGroup cols={2}>
  <Card title="User" icon="user" href="/reference/user">
    A person, invited into the org by email and usually granted access through a group.
  </Card>

  <Card title="Service Account" icon="key" href="/reference/serviceaccount">
    A non-human principal that lets CI pipelines and IaC tools authenticate with its keys.
  </Card>

  <Card title="Group" icon="users" href="/reference/group">
    A named set of users and service accounts, where a grant to the group reaches every member.
  </Card>

  <Card title="Identity" icon="fingerprint" href="/reference/identity">
    The principal you attach to a workload so policies can grant it secrets and cloud access.
  </Card>
</CardGroup>

## Key Behaviors

* **Every org starts with policies already written.** Creating one sets up a `superusers` group, an empty read-only `viewers` group, and [built-in policies](/reference/policy#built-in-policies) for every resource kind, binding `manage` to superusers and `view` to viewers.
* **Identities are how workloads get access.** Attach an [identity](/concepts/identity) to a workload and credentials arrive at runtime, stored nowhere in the container. A group holds only [users](/reference/user) and service accounts, so an identity is always named directly in a binding.
* **Grant to a group, and membership does the rest.** Bind the group once: adding a member gives them everything the group's policies grant, and removing them takes it back, with no policy edited either way.
* **A target can be a query, so resources that do not exist yet are already covered.** A query on tags, properties, or relations runs again on every request, so a resource created later that matches is covered with no edit to the policy.
* **Permissions imply each other.** `manage` covers `create`, `delete`, `edit`, and `view`, and `edit` covers `view`, so a binding usually names one permission rather than a list. What each one drags along differs per resource kind, and `edit` on a secret grants `reveal`. See the [permission model](/reference/policy#permission-model).
* **Every resource can show who reaches it.** An Access Report lists the permissions on a resource, the principals bound to each, and which policy granted them, in the Console or through `cpln <kind> access-report`. It names the groups in a binding rather than expanding them to people.
* **The [`controlplane` service account](/reference/serviceaccount#built-in-service-accounts) is bound like any other principal.** The `superusers-` policy for every resource kind names it alongside the group, which is how the platform operates the resources in your org. It shows up in the policy list and in every Access Report, exactly like a grant you wrote.

## Gotchas

* **No policy can deny.** A principal is allowed the moment any policy matches, and nothing subtracts from what another granted, so narrow access by granting less rather than by writing an exception.
* **Billing reaches into the org twice.** Creating an org needs `billing_admin` or `org_creator` on the account, and an unpaid account deactivates its orgs: every principal collapses to read-only whatever the policies say, with `This org is inactive and only read access is allowed`.
* **Group edits apply at once; user edits may not.** Changing a group's members or its query takes effect immediately. Membership that a query derives from user data is cached, so retagging a user is not a reliable way to revoke access. In a [SAML](/core/authentication#console-ui) org, membership can also come from the assertion's own claims.
* **A policy cannot reach someone who is not yet an org member.** Control Plane resolves a non-member to a principal no org policy can name, and skips group expansion for them entirely, so a binding on their email address grants nothing until they [join the org](/guides/invite-users). Invite first, then grant.
* **You cannot lock yourself out of superusers.** Removing yourself from the built-in group is refused with `You cannot remove yourself from the built-in 'superusers' group`.

## Learn More

<CardGroup cols={2}>
  <Card title="Policy reference" icon="https://mintcdn.com/controlplanecorporation-majid-docs-content-expansion/Ry1Mkgc7uPHC-gur/icons/policy.svg?fit=max&auto=format&n=Ry1Mkgc7uPHC-gur&q=85&s=3d2df0048f3707d04df9f7344b6a4a27" href="/reference/policy" width="24" height="24" data-path="icons/policy.svg">
    The permission table per resource kind, and the policies every org starts with.
  </Card>

  <Card title="Create a Policy" icon="plus" href="/guides/policy">
    Grant a group or an identity permission on a set of resources.
  </Card>

  <Card title="Identity" icon="fingerprint" href="/concepts/identity">
    What you attach to a workload to give it secrets, clouds, and private networks.
  </Card>

  <Card title="Org (Organization)" icon="building" href="/concepts/org">
    The boundary every policy lives in, and the users, groups, and service accounts it holds.
  </Card>
</CardGroup>
