> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Access Control

> Two-part access control system combining billing account roles with org-level policies. Covers principals, permissions, and fine-grained authorization.

Access control on the Control Plane Platform is handled in two separate ways: one for billing accounts, and the other for organizations (orgs).

<Tabs>
  <Tab title="Billing Account">
    Billing accounts have three roles that can be assigned when inviting users:

    | Role             | Description                                                   |
    | :--------------- | :------------------------------------------------------------ |
    | `billing_admin`  | Full administrative access to billing settings and invoices   |
    | `billing_viewer` | Read-only access to billing information                       |
    | `org_creator`    | Ability to create new organizations under the billing account |

    Billing account roles are independent from org-level policies. A `billing_admin` can manage invoices but has no implicit permissions on org resources.
  </Tab>

  <Tab title="Organization">
    For access control on [orgs](/reference/org), there is a policy system that relies on **principals** and **bindings**. This enables fine-grained authorization rules to define the minimum amount of permissions required when accessing resources of the platform.

    <Note>
      Organization access control follows the principle of least privilege - grant only the permissions necessary for a principal to perform their tasks.
    </Note>
  </Tab>
</Tabs>

***

## Principals

A "principal" is an entity that can be granted permissions. The Control Plane Platform supports four principal types, each scoped to an [org](/reference/org).

<CardGroup cols={2}>
  <Card title="User" icon="user" href="/reference/user">
    A distinct human being associated with an email. Users are members of one or more orgs and can be invited by authorized principals.
  </Card>

  <Card title="Service Account" icon="robot" href="/reference/serviceaccount">
    A non-human principal for automation and CI/CD pipelines. Service accounts can be associated with a group on creation.
  </Card>

  <Card title="Group" icon="users" href="/reference/group">
    A named collection of users and service accounts. Permissions granted to a group via policies are automatically applied to all its members.
  </Card>

  <Card title="Identity" icon="fingerprint" href="/reference/identity">
    A workload identity that grants cloud access and network resource permissions. Reusable across multiple workloads.
  </Card>
</CardGroup>

***

## Policy

A [policy](/reference/policy) governs resource access within an [org](/reference/org) by binding principals to permissions on target resources.

<AccordionGroup>
  <Accordion title="Target Resources" icon="bullseye">
    A resource is a Control Plane object (e.g., [secret](/reference/secret), [workload](/reference/workload/general), [GVC](/reference/gvc), etc.).

    A policy can target:

    * **All resources** of a specific type within your org
    * **Specific resources** assigned directly by resource self link
    * **Dynamic resources** matched using [tag queries](/core/misc#tags)

    For example, a policy can target all GVCs in your org, or specifically only "production-gvc" and "staging-gvc".
  </Accordion>

  <Accordion title="Bindings" icon="link">
    A binding maps permissions to principals:

    * **Permissions**: Actions like `create`, `delete`, `edit`, `view`, etc. The [available permissions](/reference/policy#permissions) vary by resource type.
    * **Principals**: [Users](/reference/user), [groups](/reference/group), [service accounts](/reference/serviceaccount), or [identities](/reference/identity) that receive the permissions.

    Multiple bindings can exist on a single policy, allowing different permission sets for different principals.
  </Accordion>
</AccordionGroup>

***

## Common Use Cases

<AccordionGroup>
  <Accordion title="Team access via groups">
    Create a [group](/reference/group) for your team and add users as members. Create a [policy](/reference/policy) that grants the group permissions on target resources (e.g., `view` and `edit` on specific GVCs). All group members automatically receive these permissions. When team members change, simply update group membership - no policy changes needed.
  </Accordion>

  <Accordion title="CI/CD automation with service accounts">
    Create a [service account](/reference/serviceaccount) and generate a key for authentication. Add the service account to a group with appropriate permissions, or create a policy granting it `create` and `edit` permissions on workloads. Create a CLI profile using `cpln profile create PROFILE_NAME --org ORG_NAME --token KEY --default`. The `--default` flag makes this profile active for all future commands without needing to specify `--profile` each time.
  </Accordion>

  <Accordion title="Workload access to secrets">
    Create an [identity](/reference/identity) and link it to your [workload](/reference/workload/general). Create a [policy](/reference/policy) that grants the identity `reveal` permission on the target [secret](/reference/secret). Reference the secret in your workload as an environment variable (`cpln://secret/SECRET_NAME`) or volume mount. The workload can now access the secret value at runtime.
  </Accordion>

  <Accordion title="Infrastructure as Code automation">
    Create a [service account](/reference/serviceaccount) for Terraform or Pulumi. Generate a key and configure your provider to authenticate with it. Create policies granting the service account permissions to manage the resources your IaC templates define (GVCs, workloads, secrets, identities, etc.).
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Policy Reference" icon="shield-check" href="/reference/policy">
    Detailed configuration options and permissions for policies
  </Card>

  <Card title="Create a Policy" icon="plus" href="/guides/policy">
    Step-by-step guide to creating your first policy
  </Card>
</CardGroup>