---
title: "Policies"
description: "Write policy documents, use managed policies, attach policies, and check permissions."
---

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

# Policies

A policy is a document of statements that allow or deny actions on resources. You attach policies to users, bots and groups. There are two kinds:

- **Managed policies** are built in and the same in every organization. You can't change or delete them. Their ID is their name, like `ReadOnlyAccess`.
- **Custom policies** are ones you write. Their ID is a UUID, and they also have a policy ID like `pol_a1b2c3d4e5f6` and a resource name.

For how policies combine into a decision, see [How access is decided](/iam#how-access-is-decided).

## Policy documents

```json
{
  "statements": [
    {
      "sid": "ReadProjects",
      "effect": "allow",
      "actions": ["projects.list", "projects.get"],
      "resources": ["*"]
    },
    {
      "effect": "deny",
      "actions": ["projects.delete"],
      "resources": ["ezgh:*:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2"]
    }
  ]
}
```

| Field | Required | Value |
| --- | --- | --- |
| `statements` | Yes | 1 to 20 statements |
| `sid` | No | A label for the statement, up to 64 characters |
| `effect` | Yes | `allow` or `deny` |
| `actions` | Yes | 1 to 100 actions or action patterns |
| `resources` | Yes | 1 to 100 resource names or patterns, each up to 1,024 characters |

Field names and `effect` values are lowercase. Policies have no conditions.

### Actions

Actions are named `<service>.<verb>` or `<service>.<resource>.<verb>`, like `projects.delete` or `ocr.processors.create`. In an action pattern, `*` matches any run of characters: `*` is every action, `projects.*` every projects action, and `*.list` every list action. Each action or pattern must match at least one existing action; otherwise saving the policy returns `400` with `invalid_request`. The [action reference](#action-reference) lists every action.

### Resources

A resource name identifies something a policy can target:

| Resource | Resource name |
| --- | --- |
| Organization | `ezgh::org_k3f9a0x2m7qp` |
| Project | `ezgh::org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2` |
| Group | `ezgh::org_k3f9a0x2m7qp:grp_…` |
| Bot | `ezgh::org_k3f9a0x2m7qp:bot_…` |
| Custom policy | `ezgh::org_k3f9a0x2m7qp:pol_…` |
| SSO provider | `ezgh::org_k3f9a0x2m7qp:sso_…` |
| OCR processor | `ezgh:us-west-1:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:prc_…` |

The part after `ezgh:` is the region, empty for resources that aren't regional. The console shows each group's, bot's and custom policy's **Resource name** on its page.

In `resources`:

- `*` alone is everything in the organization.
- Any other value starts with `ezgh:`, a region, and your organization's ID (`org_…`), written out. A policy can only name resources in its own organization.
- `*` matches any run of characters. `ezgh:*:org_…:prj_…` matches the project, and `ezgh:*:org_…:prj_…:*` matches everything in it, in any region.
- A pattern with an empty region can't end in `:*`, because it would miss regional resources. Use `*` as the region instead.

Each action is checked against one resource, shown as **Checked against** in the [action reference](#action-reference). Actions that create things in the organization or act on the whole organization, such as `projects.create`, `organizations.get` or `users.delete`, are checked against the organization. A statement scoped to a project doesn't allow them. This policy lets its holder see the organization and OCR models, and use OCR processors in one project only:

```json
{
  "statements": [
    {
      "effect": "allow",
      "actions": ["organizations.get", "ocr.models.list", "ocr.models.get"],
      "resources": ["*"]
    },
    {
      "effect": "allow",
      "actions": ["projects.list", "projects.get", "ocr.processors.*", "ocr.documents.process"],
      "resources": [
        "ezgh:*:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2",
        "ezgh:*:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:*"
      ]
    }
  ]
}
```

Listing projects with this policy returns only that project.

## Managed policies

| Policy | What it allows |
| --- | --- |
| `AdministratorAccess` | Every action. The root user always has it. |
| `BasicAccess` | See the organization, its projects, users and bots, and create your own API keys: `organizations.get`, `projects.list`, `projects.get`, `users.list`, `users.get`, `bots.list`, `bots.get`, `apiKeys.create`. |
| `ReadOnlyAccess` | View everything, change nothing: `*.get`, `*.list` and `audit.queries.run`, plus every product's list and read actions. |
| `ProjectsFullAccess` | Create, change and delete projects: `organizations.get`, `projects.*`. |
| `BillingFullAccess` | Manage billing details and payment methods: `organizations.get`, `billing.*`. |
| `IAMFullAccess` | Manage users, invitations, groups, bots, API keys, policies, SSO and SCIM: `organizations.get`, `users.*`, `invitations.*`, `groups.*`, `bots.*`, `apiKeys.*`, `policies.*`, `ssoProviders.*`, `scim.*`. |
| `OcrFullAccess` | Manage OCR processors, read models and process documents: every `ocr.*` action, plus `organizations.get`, `projects.list`, `projects.get`. |
| `OcrReadOnlyAccess` | Read OCR processors and models: `ocr.models.list`, `ocr.models.get`, `ocr.processors.list`, `ocr.processors.get`, plus `organizations.get`, `projects.list`, `projects.get`. |

Managed policies apply to everything in the organization. `IAMFullAccess` includes `policies.attach`, which lets its holder attach any policy to themselves, so treat it as administrator access.

To see a policy's full document, open **IAM** > **Policies** and select it, or run `ezgh iam policies get <policy>`.

## Create a custom policy

Creating a policy needs `policies.create`. A policy's name is 1 to 100 characters and its description up to 1,000.

### Console

1. Open **IAM** > **Policies** and select **Create policy**.
2. Enter a **Name** and, optionally, a **Description**.
3. Under **Applies to**, choose **Everything in the organization** or **Only some projects**. Select the actions to **Allow**, and optionally **Add denied actions**. To write the document yourself, select **Edit as JSON**.
4. Review, then select **Create policy**.
### CLI

```sh
ezgh iam policies create deployers --document @policy.json --description "Deploy to production"
```
### API

```sh
curl https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/policies \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "deployers", "document": {"statements": [{"effect": "allow", "actions": ["projects.*"], "resources": ["*"]}]}}'
```

See [CreatePolicy](/orgs-api/policies/CreatePolicy/).

To change a custom policy, select **Edit** on its page (`policies.update`), run `ezgh iam policies update`, or call [UpdatePolicy](/orgs-api/policies/UpdatePolicy/). Changes apply to everyone it's attached to on their next request. Deleting a custom policy (`policies.delete`) detaches it from every user, bot and group.

## Attach a policy

Attach policies to users, bots and groups. Attaching and detaching needs `policies.attach`. You can't change the root user's policies: the root user always has `AdministratorAccess`.

### Console

1. Open the user's, bot's or group's page under **IAM**.
2. On the **Permissions** tab, select **Edit policies**.
3. Select the policies, then **Save**.

The **Permissions** tab lists every policy that applies, and whether it's attached **Directly** or **Via group**.
### CLI

```sh
ezgh iam policies attach ReadOnlyAccess --user ada@example.com
ezgh iam policies attach deployers --bot deployer
ezgh iam policies detach ReadOnlyAccess --group developers
```
### API

```sh
curl -X POST https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/users/$USER_ID/policies/ReadOnlyAccess \
  -H "Authorization: Bearer $EZGH_API_KEY"
```

Use the policy's ID: a managed policy's name, or a custom policy's UUID. See [AttachUserPolicy](/orgs-api/policies/AttachUserPolicy/), [AttachBotPolicy](/orgs-api/policies/AttachBotPolicy/), [AttachGroupPolicy](/orgs-api/policies/AttachGroupPolicy/), and [SetUserPolicies](/orgs-api/policies/SetUserPolicies/) to replace all of a user's policies.

## Check permissions

Ask which actions you're allowed, on the organization or on one resource. The answer is for whoever makes the request: your session, or the API key's owner.

### CLI

```sh
ezgh iam permissions check
ezgh iam permissions check projects.delete --resource ezgh::org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2
```

Without actions, it lists every action you're allowed. With actions, it exits with status 4 if any is denied.
### API

```sh
curl "https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/permissions?actions=projects.delete&resource=ezgh::org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2" \
  -H "Authorization: Bearer $EZGH_API_KEY"
```

`allowed` lists the allowed actions on the resource. `allowedSomewhere` lists the actions allowed on at least one resource. See [GetPermissions](/orgs-api/policies/GetPermissions/).

## Action reference

Every action a policy can name. Products add their own actions; `ezgh iam actions list` and [ListActions](/orgs-api/policies/ListActions/) return the current list. `AdministratorAccess` allows every action; **Managed policies** lists the other managed policies that allow each one.

**Access level** is how `ReadOnlyAccess` treats the action: it allows list and read actions, never write actions.

### Organizations

| Action | Description | Access level | Checked against | Managed policies |
| --- | --- | --- | --- | --- |
| `organizations.get` | View the organization | Read | Organization | BasicAccess, ReadOnlyAccess, ProjectsFullAccess, BillingFullAccess, IAMFullAccess, OcrFullAccess, OcrReadOnlyAccess |
| `organizations.update` | Rename the organization | Write | Organization | None |
| `projects.list` | List projects | List | Project | BasicAccess, ReadOnlyAccess, ProjectsFullAccess, OcrFullAccess, OcrReadOnlyAccess |
| `projects.get` | View a project | Read | Project | BasicAccess, ReadOnlyAccess, ProjectsFullAccess, OcrFullAccess, OcrReadOnlyAccess |
| `projects.create` | Create projects | Write | Organization | ProjectsFullAccess |
| `projects.update` | Rename projects | Write | Project | ProjectsFullAccess |
| `projects.delete` | Delete projects | Write | Project | ProjectsFullAccess |

### IAM

| Action | Description | Access level | Checked against | Managed policies |
| --- | --- | --- | --- | --- |
| `users.list` | List the organization's users | List | Organization | BasicAccess, ReadOnlyAccess, IAMFullAccess |
| `users.get` | View a user, with their groups and policies | Read | Organization | BasicAccess, ReadOnlyAccess, IAMFullAccess |
| `users.delete` | Remove users from the organization, revoking their API keys | Write | Organization | IAMFullAccess |
| `users.reactivate` | Reactivate users your identity provider suspended, after SCIM provisioning is turned off | Write | Organization | IAMFullAccess |
| `invitations.list` | List invitations to the organization | List | Organization | ReadOnlyAccess, IAMFullAccess |
| `invitations.get` | View an invitation | Read | Organization | ReadOnlyAccess, IAMFullAccess |
| `invitations.create` | Invite people to the organization | Write | Organization | IAMFullAccess |
| `invitations.delete` | Revoke invitations | Write | Organization | IAMFullAccess |
| `groups.list` | List groups and their members | List | Group | ReadOnlyAccess, IAMFullAccess |
| `groups.create` | Create groups | Write | Organization | IAMFullAccess |
| `groups.update` | Rename groups | Write | Group | IAMFullAccess |
| `groups.delete` | Delete groups | Write | Group | IAMFullAccess |
| `groups.updateMembers` | Add and remove users and bots in groups | Write | Group | IAMFullAccess |
| `bots.list` | List bots | List | Bot | BasicAccess, ReadOnlyAccess, IAMFullAccess |
| `bots.get` | View a bot, with its groups and policies | Read | Bot | BasicAccess, ReadOnlyAccess, IAMFullAccess |
| `bots.create` | Create bots | Write | Organization | IAMFullAccess |
| `bots.update` | Rename bots | Write | Bot | IAMFullAccess |
| `bots.delete` | Delete bots and their API keys | Write | Bot | IAMFullAccess |
| `bots.createApiKey` | Create API keys that act as a bot | Write | Bot | IAMFullAccess |
| `apiKeys.list` | List every API key in the organization (everyone sees their own) | List | Organization | ReadOnlyAccess, IAMFullAccess |
| `apiKeys.create` | Create API keys for yourself | Write | Organization | BasicAccess, IAMFullAccess |
| `apiKeys.delete` | Revoke any API key (everyone can revoke their own) | Write | Organization | IAMFullAccess |
| `policies.list` | List and read policies | List | Policy | ReadOnlyAccess, IAMFullAccess |
| `policies.create` | Create custom policies | Write | Organization | IAMFullAccess |
| `policies.update` | Edit custom policies | Write | Policy | IAMFullAccess |
| `policies.delete` | Delete custom policies | Write | Policy | IAMFullAccess |
| `policies.attach` | Attach and detach policies on users, bots and groups | Write | Organization | IAMFullAccess |
| `scim.get` | View SCIM provisioning's settings and status | Read | Organization | ReadOnlyAccess, IAMFullAccess |
| `scim.tokens.list` | List SCIM tokens | List | Organization | ReadOnlyAccess, IAMFullAccess |
| `scim.tokens.create` | Create SCIM tokens for an identity provider (turns SCIM provisioning on) | Write | Organization | IAMFullAccess |
| `scim.tokens.delete` | Delete SCIM tokens (the last one turns SCIM provisioning off) | Write | Organization | IAMFullAccess |
| `ssoProviders.list` | List SSO identity providers | List | Organization | ReadOnlyAccess, IAMFullAccess |
| `ssoProviders.create` | Add SSO identity providers | Write | Organization | IAMFullAccess |
| `ssoProviders.update` | Change how SSO providers' groups map to EZGH groups | Write | SSO provider | IAMFullAccess |
| `ssoProviders.delete` | Remove SSO identity providers | Write | SSO provider | IAMFullAccess |
| `ssoProviders.verifyDomain` | Verify SSO providers' email domains | Write | SSO provider | IAMFullAccess |

### Billing

| Action | Description | Access level | Checked against | Managed policies |
| --- | --- | --- | --- | --- |
| `billing.preferences.get` | View billing contact and address | Read | Organization | ReadOnlyAccess, BillingFullAccess |
| `billing.preferences.update` | Change billing contact and address | Write | Organization | BillingFullAccess |
| `billing.paymentMethods.list` | List payment methods | List | Organization | ReadOnlyAccess, BillingFullAccess |
| `billing.paymentMethods.create` | Add payment methods | Write | Organization | BillingFullAccess |
| `billing.paymentMethods.update` | Change the default payment method | Write | Organization | BillingFullAccess |
| `billing.paymentMethods.delete` | Remove payment methods | Write | Organization | BillingFullAccess |
| `billing.balance.get` | View the amount due, credit remaining and estimated bill | Read | Organization | ReadOnlyAccess, BillingFullAccess |
| `billing.invoices.list` | List invoices | List | Organization | ReadOnlyAccess, BillingFullAccess |
| `billing.invoices.get` | View invoices and download their PDFs | Read | Organization | ReadOnlyAccess, BillingFullAccess |
| `billing.ledger.list` | View the billing statement (ledger activity) | List | Organization | ReadOnlyAccess, BillingFullAccess |
| `billing.costs.get` | View costs and usage | Read | Organization | ReadOnlyAccess, BillingFullAccess |
| `billing.pricing.get` | View prices | Read | Organization | ReadOnlyAccess, BillingFullAccess |

### Trails

| Action | Description | Access level | Checked against | Managed policies |
| --- | --- | --- | --- | --- |
| `audit.events.list` | View the organization's audit log | List | Organization | ReadOnlyAccess |
| `audit.queries.run` | Run SQL queries on the organization's audit log | Read | Organization | ReadOnlyAccess |
| `audit.queries.get` | See an audit log query's status and results | Read | Organization | ReadOnlyAccess |
| `audit.queries.list` | See everyone's audit log query history | List | Organization | ReadOnlyAccess |
| `audit.queries.cancel` | Cancel running audit log queries | Write | Organization | None |

### Service Quotas

| Action | Description | Access level | Checked against | Managed policies |
| --- | --- | --- | --- | --- |
| `quotas.quotas.list` | List service quotas, their values and usage | List | Organization | ReadOnlyAccess |
| `quotas.quotas.get` | View a service quota, its values and usage | Read | Organization | ReadOnlyAccess |

### OCR

| Action | Description | Access level | Checked against | Managed policies |
| --- | --- | --- | --- | --- |
| `ocr.models.list` | List OCR models | List | Organization | ReadOnlyAccess, OcrFullAccess, OcrReadOnlyAccess |
| `ocr.models.get` | View an OCR model | Read | Organization | ReadOnlyAccess, OcrFullAccess, OcrReadOnlyAccess |
| `ocr.processors.list` | List a project's processors | List | Project | ReadOnlyAccess, OcrFullAccess, OcrReadOnlyAccess |
| `ocr.processors.create` | Create processors in a project | Write | Project | OcrFullAccess |
| `ocr.processors.get` | View a processor | Read | Processor | ReadOnlyAccess, OcrFullAccess, OcrReadOnlyAccess |
| `ocr.processors.update` | Update a processor | Write | Processor | OcrFullAccess |
| `ocr.processors.delete` | Delete a processor | Write | Processor | OcrFullAccess |
| `ocr.processors.disable` | Disable a processor | Write | Processor | OcrFullAccess |
| `ocr.processors.enable` | Enable a processor | Write | Processor | OcrFullAccess |
| `ocr.documents.process` | Process documents with a processor | Write | Processor | OcrFullAccess |

Source: https://docs.ezghcloud.com/iam/policies/index.mdx