- HTTP request
- Path parameters
- Query parameters
- Request body
- Response body
- Authorization scopes
- IAM Permissions
- Try it!
Gets the access control policy for a resource. May be empty if no such policy or resource exists.
HTTP request
GET https://compute.googleapis.com/compute/v1/projects/{project}/zones/{zone}/instances/{resource}/getIamPolicy
The URL uses gRPC Transcoding syntax.
Path parameters
Parameters | |
---|---|
project |
Project ID for this request. |
zone |
The name of the zone for this request. |
resource |
Name or id of the resource for this request. |
Query parameters
Parameters | |
---|---|
optionsRequestedPolicyVersion |
Requested IAM Policy version. |
Request body
The request body must be empty.
Response body
An Identity and Access Management (IAM) policy, which specifies access controls for Google Cloud resources.
A Policy
is a collection of bindings
. A binding
binds one or more members
, or principals, to a single role
. Principals can be user accounts, service accounts, Google groups, and domains (such as G Suite). A role
is a named list of permissions; each role
can be an IAM predefined role or a user-created custom role.
For some types of Google Cloud resources, a binding
can also specify a condition
, which is a logical expression that allows access to a resource only if the expression evaluates to true
. A condition can add constraints based on attributes of the request, the resource, or both. To learn which resources support conditions in their IAM policies, see the IAM documentation.
JSON example:
{
"bindings": [
{
"role": "roles/resourcemanager.organizationAdmin",
"members": [
"user:mike@example.com",
"group:admins@example.com",
"domain:google.com",
"serviceAccount:my-project-id@appspot.gserviceaccount.com"
]
},
{
"role": "roles/resourcemanager.organizationViewer",
"members": [
"user:eve@example.com"
],
"condition": {
"title": "expirable access",
"description": "Does not grant access after Sep 2020",
"expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",
}
}
],
"etag": "BwWWja0YfJA=",
"version": 3
}
YAML example:
bindings:
- members:
- user:mike@example.com
- group:admins@example.com
- domain:google.com
- serviceAccount:my-project-id@appspot.gserviceaccount.com
role: roles/resourcemanager.organizationAdmin
- members:
- user:eve@example.com
role: roles/resourcemanager.organizationViewer
condition:
title: expirable access
description: Does not grant access after Sep 2020
expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
etag: BwWWja0YfJA=
version: 3
For a description of IAM and its features, see the IAM documentation.
If successful, the response body contains data with the following structure:
JSON representation |
---|
{ "version": integer, "bindings": [ { "role": string, "members": [ string ], "condition": { "expression": string, "title": string, "description": string, "location": string } } ], "auditConfigs": [ { "service": string, "auditLogConfigs": [ { "logType": enum, "exemptedMembers": [ string ] } ] } ], "etag": string } |
Fields | |
---|---|
version |
Specifies the format of the policy. Valid values are Any operation that affects conditional role bindings must specify version
Important: If you use IAM Conditions, you must include the If a policy does not include any conditions, operations on that policy may specify any valid version or leave the field unset. To learn which resources support conditions in their IAM policies, see the IAM documentation. |
bindings[] |
Associates a list of The |
bindings[].role |
Role that is assigned to the list of For an overview of the IAM roles and permissions, see the IAM documentation. For a list of the available pre-defined roles, see here. |
bindings[].members[] |
Specifies the principals requesting access for a Google Cloud resource.
|
bindings[].condition |
The condition that is associated with this binding. If the condition evaluates to If the condition evaluates to To learn which resources support conditions in their IAM policies, see the IAM documentation. |
bindings[].condition.expression |
Textual representation of an expression in Common Expression Language syntax. |
bindings[].condition.title |
Optional. Title for the expression, i.e. a short string describing its purpose. This can be used e.g. in UIs which allow to enter the expression. |
bindings[].condition.description |
Optional. Description of the expression. This is a longer text which describes the expression, e.g. when hovered over it in a UI. |
bindings[].condition.location |
Optional. String indicating the location of the expression for error reporting, e.g. a file name and a position in the file. |
auditConfigs[] |
Specifies cloud audit logging configuration for this policy. |
auditConfigs[].service |
Specifies a service that will be enabled for audit logging. For example, |
auditConfigs[].auditLogConfigs[] |
The configuration for logging of each type of permission. |
auditConfigs[].auditLogConfigs[].logType |
The log type that this config enables. |
auditConfigs[].auditLogConfigs[].exemptedMembers[] |
Specifies the identities that do not cause logging for this type of permission. Follows the same format of |
etag |
Important: If you use IAM Conditions, you must include the A base64-encoded string. |
Authorization scopes
Requires one of the following OAuth scopes:
https://www.googleapis.com/auth/compute.readonly
https://www.googleapis.com/auth/compute
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview.
IAM Permissions
In addition to any permissions specified on the fields above, authorization requires one or more of the following IAM permissions:
compute.instances.getIamPolicy
To find predefined roles that contain those permissions, see Compute Engine IAM Roles.