This page describes how to manage existing access levels. You can:

- [List access levels](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels.md.txt#list_access_levels)

- [List access levels (formatted)](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels.md.txt#formatted_access_levels)

- [Describe an access level](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels.md.txt#describe_an_access_level)

- [Update an access level](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels.md.txt#update_an_access_level)

- [Delete an access level](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels.md.txt#delete_an_access_level)

## Before you begin

> [!WARNING]
> **Warning:** If you share an access level across Google Cloud and Google Workspace, modifying or deleting that access level can impact user access. For more information, see the [Google Workspace documentation](https://support.google.com/a/answer/13570967).

- [Set your default access policy](https://docs.cloud.google.com/access-context-manager/docs/manage-access-policy.md.txt#set-default) for using the Google Cloud CLI.

  *-or-*

  [Get the name of your policy.](https://docs.cloud.google.com/access-context-manager/docs/manage-access-policy.md.txt#get_the_name_of_an_access_policy) The policy name is required
  for commands using the gcloud CLI and making API calls. If you
  set a default access policy, you don't need to specify the policy for the
  gcloud CLI.
- Ensure that you have an Identity and Access Management (IAM) role at the organization
  level that lets you manage access levels. Ask your administrator to grant
  you one of the following roles, or a custom role with the same permissions:

  - **To view access levels:** [Access Context Manager Reader](https://docs.cloud.google.com/iam/docs/roles-permissions/accesscontextmanager.md.txt#accesscontextmanager.policyReader)
    (`roles/accesscontextmanager.policyReader`)

  - **To view and change access levels:**
    [Access Context Manager Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/accesscontextmanager.md.txt#accesscontextmanager.policyEditor)
    (`roles/accesscontextmanager.policyEditor`) or
    [Access Context Manager Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/accesscontextmanager.md.txt#accesscontextmanager.policyAdmin)
    (`roles/accesscontextmanager.policyAdmin`)

## List access levels

### Console

To list all access levels, open the **Access Context Manager**
page in the Google Cloud console and then, if prompted,
select your organization. The page displays your organization's access
levels in a grid, including details about the configuration of each access
level.

[Open the Access Context Manager page](https://console.cloud.google.com/security/access-level)

### gcloud

To list all access levels, use the [`list`](https://docs.cloud.google.com/sdk/gcloud/reference/access-context-manager/levels/list.md.txt) command.

```bash
gcloud access-context-manager levels list \
  [--policy=POLICY_NAME]
```

Replace the following:

- `POLICY_NAME`: the name of your organization's access policy. This value is required only if you haven't set a [default access policy](https://docs.cloud.google.com/access-context-manager/docs/manage-access-policy.md.txt#set-default).

The output is similar to the following:

```
NAME             TITLE                  LEVEL_TYPE
Device_Trust     Device_Trust Extended  Basic
Service_Group_A  Service_Group_A        Basic
```

### API

To list all the access levels for a policy, call
[`accessLevels.list`](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/v1/accessPolicies.accessLevels/list.md.txt).

```
GET https://accesscontextmanager.googleapis.com/v1/accessPolicies/POLICY_NAME/accessLevels
```

Replace the following:

- `POLICY_NAME`: the name of your organization's access policy.

### Request body

The request body must be empty.

### Optional parameters

Optionally, include one or more of the following query parameters.

| Parameters ||
|---|---|
| `pageSize` | `number` By default, the list of [access levels](https://docs.cloud.google.com/access-context-manager/docs/overview.md.txt#access-levels) returned by `accessLevels.list` is paginated. Each page is limited to 100 access levels. You can use this parameter to modify the number of access levels that are returned per page. |
| `pageToken` | `string` If the number of access levels returned by your call exceeded the page size, the response body includes a page token. You can use this parameter in a subsequent call to obtain the next page of results. |

### Response body

If successful, the response body for the call contains an
[`AccessLevels`](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/v1/accessPolicies.accessLevels.md.txt#AccessLevel) object that lists the access levels,
and a [`nextPageToken`](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/v1/accessPolicies.accessLevels/list.md.txt#body.ListAccessLevelsResponse.FIELDS.next_page_token) string. `nextPageToken` only
has a value if the number of access levels returned exceeds the
[page size](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels.md.txt#pageSize). Otherwise, `nextPageToken` is returned as an
empty string.

## List access levels (formatted)

Using the gcloud CLI, you can obtain a list of your access levels in
YAML or JSON format.

To get a formatted list of access levels, use the [`list`](https://docs.cloud.google.com/sdk/gcloud/reference/access-context-manager/levels/list.md.txt) command.

```bash
gcloud access-context-manager levels list \
  --format=FORMAT \
  [--policy=POLICY_NAME]
```

Replace the following:

- `FORMAT`: one of the following values:

  - `list` (YAML format)

  - `json` (JSON format)

- `POLICY_NAME`: the name of your organization's access policy.
  This value is required only if you haven't set a
  [default access policy](https://docs.cloud.google.com/access-context-manager/docs/manage-access-policy.md.txt#set-default).

The YAML output is similar to the following:

```yaml
- basic: {'conditions': [{'ipSubnetworks': ['192.0.2.0/24']}]}
  description: Level for corp access.
  name: accessPolicies/123456789012/accessLevels/corp_level
  title: Corp Level
- basic: {'combiningFunction': 'OR', 'conditions': [{'ipSubnetworks': ['192.0.2.0/24']}]}
  description: Level for net access.
  name: accessPolicies/123456789012/accessLevels/net_level
  title: Net Level
```

<br />

The JSON output is similar to the following:

```json
[
  {
    "basic": {
      "conditions": [
        {
          "ipSubnetworks": [
            "192.0.2.0/24"
          ]
        }
      ]
    },
    "description": "Level for corp access.",
    "name": "accessPolicies/123456789012/accessLevels/corp_level",
    "title": "Corp Level"
  },
  {
    "basic": {
      "combiningFunction": "OR",
      "conditions": [
        {
          "ipSubnetworks": [
            "192.0.2.0/24"
          ]
        }
      ]
    },
    "description": "Level for net access.",
    "name": "accessPolicies/123456789012/accessLevels/net_level",
    "title": "Net Level"
  }
]
```

<br />

## Describe an access level

### Console

Using Google Cloud console, refer to the steps to
[list access levels](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels.md.txt#list_access_levels). When you list your access
levels, details are provided in the grid that appears.

### gcloud

Listing access levels only provides their name, title, and level type. To
get detailed information about what a level actually does, use the
`describe` command.

```bash
gcloud access-context-manager levels describe LEVEL_NAME \
    [--policy=POLICY_NAME]
```

Replace the following:

- `LEVEL_NAME`: the name of the access level that you want to
  describe.

- `POLICY_NAME`: the name of your organization's access policy.
  This value is required only if you haven't set a
  [default access policy](https://docs.cloud.google.com/access-context-manager/docs/manage-access-policy.md.txt#set-default).

The command prints information about the level formatted as YAML. For
example, if the level restricts access to certain operating system
versions, the output is similar to the following:

```yaml
basic:
  conditions:
  - devicePolicy:
      allowedEncryptionStatuses:
      - ENCRYPTED
      osConstraints:
      - minimumVersion: 10.13.6
        osType: DESKTOP_MAC
      - minimumVersion: 10.0.18219
        osType: DESKTOP_WINDOWS
      - minimumVersion: 68.0.3440
        osType: DESKTOP_CHROME_OS
      requireScreenlock: true
name: accessPolicies/123456789012/accessLevels/Device_Trust
title: Device_Trust Extended
```

> [!NOTE]
> **Note:** To use the output of the describe command to update or create a basic access level, send the response to a YAML file, and then edit the file to remove the `name`, `title`, `description`, `basic`, and `conditions` lines.

### API

Listing access levels only provides the name, title, and type of the levels.
To get detailed information about an access level,
call [`accessLevels.get`](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/v1/accessPolicies.accessLevels/get.md.txt).

```
GET https://accesscontextmanager.googleapis.com/v1/accessPolicies/POLICY_NAME/accessLevels/LEVEL_NAME
```

Replace the following:

- `POLICY_NAME`: the name of your organization's access policy.

- `LEVEL_NAME`: the name of the access level that you want to
  describe.

### Request body

The request body must be empty.

### Response body

If successful, the response body for the call contains an
[`AccessLevel`](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/v1/accessPolicies.accessLevels.md.txt#AccessLevel) resource that includes details about
what the access level does, the last time the level was updated, and more.

## Update an access level

This section describes how to update individual access levels. To update
all of your organization's access levels in one operation, see
[Making bulk changes to access levels](https://docs.cloud.google.com/access-context-manager/docs/bulk-operations.md.txt).

### Console

To update an access level:

1. Open the **Access Context Manager** page in the Google Cloud console.

   [Open the Access Context Manager page](https://console.cloud.google.com/security/access-level)
2. If you are prompted, select your organization.

3. In the grid, click the name of the access level that you want to update.

4. In the **Edit Access Level** pane, make changes to the access level.

   For a complete list of the attributes that you can add or modify,
   read about [access level attributes](https://docs.cloud.google.com/access-context-manager/docs/access-level-attributes.md.txt).
5. Click **Save**.

   In addition to updating or removing any existing conditions,
   you can add new conditions and add new attributes to existing
   conditions.

### gcloud

Use the [`update`](https://docs.cloud.google.com/sdk/gcloud/reference/access-context-manager/levels/update.md.txt) command to update an access level.

**Basic access level:**

```bash
gcloud access-context-manager levels update LEVEL_NAME \
    --basic-level-spec=FILE \
    [--policy=POLICY_NAME]
```

**Custom access level:**

```bash
gcloud access-context-manager levels update LEVEL_NAME \
    --custom-level-spec=FILE \
    [--policy=POLICY_NAME]
```

Replace the following:

- `LEVEL_NAME`: the name of the access level that you want to
  update.

- `FILE`: the name of a YAML file that defines
  [the conditions for the access level](https://docs.cloud.google.com/access-context-manager/docs/example-yaml-file.md.txt) (for basic access levels)
  or a [CEL expression](https://docs.cloud.google.com/access-context-manager/docs/custom-access-level-spec.md.txt) that resolves to a single boolean
  value (for custom access levels).

  For a complete list of the attributes that you can use in your basic
  access level conditions,
  read about [access level attributes](https://docs.cloud.google.com/access-context-manager/docs/access-level-attributes.md.txt).
- `POLICY_NAME`: the name of your organization's access policy.
  This value is required only if you haven't set a
  [default access policy](https://docs.cloud.google.com/access-context-manager/docs/manage-access-policy.md.txt#set-default).

- You can include one or more of the following options.

  | Options ||
  |---|---|
  | `combine-function` | This option is only used for *basic access levels*. Determines how conditions are combined. Valid values: `AND`, `OR` |
  | `description` | A long-form description of the access level. |
  | `title` | A short title for the access level. The access level's title is displayed in the Google Cloud console. |

  You can include any of the [gcloud-wide flags](https://docs.cloud.google.com/sdk/gcloud/reference.md.txt).

### Example command

```bash
gcloud access-context-manager levels update Device_Trust \
    --basic-level-spec=corpdevspec.yaml \
    --combine-function=OR \
    --description='Access level that conforms to updated corporate spec.' \
    --title='Device_Trust Extended' \
    --policy=123456789012
```

### API

To update an access level, call [`accessLevels.patch`](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/v1/accessPolicies.accessLevels/patch.md.txt).

```
PATCH https://accesscontextmanager.googleapis.com/v1/accessPolicies/POLICY_NAME/accessLevels/LEVEL_NAME?updateMask=FIELDS
```

Replace the following:

- `POLICY_NAME`: the name of your organization's access policy.

- `LEVEL_NAME`: the name of the access level that you want to
  update.

- `FIELDS`: a comma-separated list of
  [fully-qualified field names](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/v1/accessPolicies.accessLevels/patch.md.txt#query-parameters) that you are updating.

### Request body

The request body must include an [`AccessLevel`](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/v1/accessPolicies.accessLevels.md.txt#AccessLevel)
resource that specifies the changes you want to make to the access level.

### Response body

If successful, the response body for the call contains an
[`Operation`](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/Shared.Types/Operation.md.txt) resource that provides details about the
patch operation.

## Delete an access level

This section describes how to delete Access Context Manager access levels.
Deleting an access level is a two-step process:

1. [Check access level dependencies](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels.md.txt#check-access-level-dependencies).

2. [Delete an individual access level](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels.md.txt#delete-an-individual-access-level).

### Check access level dependencies

Before you delete an access level, ensure that it isn't referenced by other
access levels, VPC Service Controls service perimeters, Google Workspace
Context-Aware Access policies,
[Google Cloud access bindings](https://docs.cloud.google.com/access-context-manager/docs/manage-access-bindings.md.txt),
or IAM conditions.

> [!NOTE]
> **Note:** Access Context Manager blocks deleting an access level that is referenced by another access level, a VPC Service Controls service perimeter, or a Google Workspace Context-Aware Access policy in the Google Admin console. If deletion fails because the access level is used in a Google Workspace Context-Aware Access policy, see [Cannot delete an access level used in Google Workspace Context-Aware Access policies](https://docs.cloud.google.com/access-context-manager/docs/troubleshooting.md.txt#cannot-delete-access-level-workspace-caa).

> [!WARNING]
> **Warning:** Access Context Manager doesn't block deleting an access level that is referenced only by a [Google Cloud access binding](https://docs.cloud.google.com/access-context-manager/docs/manage-access-bindings.md.txt) (which you can inspect by running `gcloud access-context-manager cloud-bindings list`) or an IAM condition. Deleting an access level that is still used in a Google Cloud access binding or IAM condition causes access evaluations to fail closed and can lock users out of the Google Cloud console and Google Cloud APIs. For recovery steps, see [Locked out of the Google Cloud console after deleting or modifying an access level](https://docs.cloud.google.com/access-context-manager/docs/troubleshooting.md.txt#locked-out-access-binding).

To find all access levels that reference the one that you want to delete, do the
following:

1. Make sure that you have installed `jq`. To verify that `jq` is installed,
   run `jq --version`. If needed, [install `jq`](https://jqlang.org/download/).

2. Check for access level dependencies. This command lists
   all access levels, then uses `jq` to filter for access levels that
   reference `LEVEL_NAME` in basic or custom level
   definitions.

   ```bash
   echo "Searching for Access Levels referencing: accessPolicies/POLICY_NAME/accessLevels/LEVEL_NAME"
   echo ""

   gcloud access-context-manager levels list \
     --policy="POLICY_NAME" \
     --format=json | \
   jq -r '
     .[] |
     select(
       # Check basic levels: Is the target access level present as an element in any requiredAccessLevels array?
       ([(.basic.conditions // [])[] | (.requiredAccessLevels // []) | index("accessPolicies/POLICY_NAME/accessLevels/LEVEL_NAME") != null] | any)
       or
       # Check custom levels: Does the expression string contain the target access level?
       ((.custom.expr.expression // "") | (contains("accessPolicies/POLICY_NAME/accessLevels/LEVEL_NAME") or contains("levels.LEVEL_NAME")))
     ) |
     "  - \(.title) (Name: \(.name))"
   '

   echo ""
   echo "If any levels are listed, they reference LEVEL_NAME. You must update these referencing levels before you delete LEVEL_NAME."
   ```

   Replace the following:
   - `POLICY_NAME`: the name of your organization's
     access policy. This value is required only if you haven't set a
     [default access policy](https://docs.cloud.google.com/access-context-manager/docs/manage-access-policy.md.txt#set-default).

   - `LEVEL_NAME`: the name of the access level that you want
     to delete---for example, `my_level`.

   In the output, any access levels that reference
   `accessPolicies/POLICY_NAME/accessLevels/LEVEL_NAME`
   or `levels.LEVEL_NAME` are listed, along with their
   `title` and `name`. These access levels include the following:
   - Basic levels, where `accessPolicies/POLICY_NAME/accessLevels/LEVEL_NAME`
     is listed in `requiredAccessLevels`

   - Custom levels, where `accessPolicies/POLICY_NAME/accessLevels/LEVEL_NAME`
     or `levels.LEVEL_NAME` is listed in the
     `custom.expr.expression` string.

3. If the command lists any referencing access
   levels, you must first update those levels to remove the dependency. For
   instructions, see [Update an access level](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels.md.txt#update_an_access_level).

After all references are removed, you can proceed with [deleting the individual
access level](https://docs.cloud.google.com/access-context-manager/docs/manage-access-levels#delete-an-individual-access-level).

### Delete an individual access level

### Console

To delete an access level:

1. Open the **Access Context Manager** page in the Google Cloud console.

   [Open the Access Context Manager page](https://console.cloud.google.com/security/access-level)
2. If you are prompted, select your organization.

3. In the grid, in the row for the access level that you want to delete,
   click the button.

4. Click **Delete**.

5. In the dialog that appears, confirm that you want to delete the
   access level.

### gcloud

To delete an access level:

1. Use the [`delete`](https://docs.cloud.google.com/sdk/gcloud/reference/access-context-manager/levels/delete.md.txt) command to delete an access level.

   ```bash
   gcloud access-context-manager levels delete LEVEL_NAME \
       [--policy=POLICY_NAME]
   ```

   Replace the following:
   - `LEVEL_NAME`: the name of the access level that you want
     to delete.

   - `POLICY_NAME`: the name of your organization's
     access policy. This value is required only if you haven't set a
     [default access policy](https://docs.cloud.google.com/access-context-manager/docs/manage-access-policy.md.txt#set-default).

2. Confirm that you want to delete the access level.

   For example:

   ```
   You are about to delete level Device_Trust

   Do you want to continue (Y/n)?
   ```

   You should see output similar to the following:

   ```
   Waiting for operation [accessPolicies/123456789012/accessLevels/Device_Trust/delete/1531171874311645] to complete...done.
   Deleted level [Device_Trust].
   ```

### API

To delete an access level, call [`accessLevels.delete`](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/v1/accessPolicies.accessLevels/delete.md.txt).

```
DELETE https://accesscontextmanager.googleapis.com/v1/accessPolicies/POLICY_NAME/accessLevels/LEVEL_NAME
```

Replace the following:

- `POLICY_NAME`: the name of your organization's access policy.

- `LEVEL_NAME`: the name of the access level that you want to
  delete.

### Request body

The request body must be empty.

### Response body

If successful, the response body for the call contains an
[`Operation`](https://docs.cloud.google.com/access-context-manager/docs/reference/rest/Shared.Types/Operation.md.txt) resource that provides details about the
delete operation.