Request temporary elevated access with Privileged Access Manager

To temporarily elevate your privileges, you can request a grant against anentitlement inPrivileged Access Manager (PAM) for a fixedduration.

An entitlement containsroles that are grantedto you after your grant request is successful. These roles are removed byPrivileged Access Manager when the grant ends.

Keep the following in mind when you want to request a grant against anentitlement:

  • You can only request grants against entitlements that you have been added to.To be added to an entitlement, contact the principal administering theentitlement.

  • One user can have a maximum of 10 open grants per entitlement at a time;these grants can be in either theActive orApproval awaited state.

  • You can't request a grant with the same scope as an existing grant in theActive orApproval awaited state.

  • Depending on how it's set up, a grant request might require approval to begranted.

  • If a grant request requires approval and isn't approved or denied in 24 hours,the grant status is changed toExpired. After this, you must make a newgrant request if you still need elevated privileges.

  • Successful grant requests might take a few minutes to take effect.

Request a grant

Console

  1. Go to thePrivileged Access Manager page.

    Go to Privileged Access Manager

  2. Select the organization, folder, or project where you want to request a grant.

  3. In theMy entitlements tab, find the entitlement to request against, andthen clickRequest grant in the same row.

    For entitlements that are inherited from a parent folder or organization,the scope of the grant is automatically adjusted to the selected organization,folder, or project. You can request a grant againstthe inherited entitlement at the child resource level.This feature is available inpreview.

  4. If the Security Command Center Premium or Enterprise tier is activated at the organizationlevel, thenyou can customize the scope of your grant request to include only somespecific roles and resources. This feature is available inpreview.

    1. Turn on theCustomize scope toggle.
    2. Add the required resource filters.You can add up to five resource filters.
    3. Select the required roles.
  5. Provide the following details:

    • The duration required for the grant, up to the maximum duration set on theentitlement.

    • If required, a justification for the grant.

    • Optional: Email addresses for notifications.

      Google identities associated with the entitlement, like approvers andrequesters, are automatically notified. However, if you want to notifyadditional people, then you can add their email addresses. This isespecially useful if you're usingworkforce identitiesinstead of Google Accounts.

  6. ClickRequest grant.

gcloud

You can request a grant by using one of the following options:

Request a grant against an entitlement

Thegcloud alpha pam grants create command requests a grant.

Before using any of the command data below, make the following replacements:

  • ENTITLEMENT_ID: The entitlement ID to create the grant against.
  • GRANT_DURATION: The requested duration of the grant, in seconds.
  • JUSTIFICATION: The justification for requesting the grant.
  • EMAIL_ADDRESS: Optional. Additional email addresses to notify of the grant request. Google identities associated with approvers are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.
  • RESOURCE_TYPE: Optional. The resource type that the entitlement belongs to. Use the valueorganization,folder, orproject.
  • RESOURCE_ID: Used withRESOURCE_TYPE. The ID of the Google Cloud project, folder, or organization that you want to manage entitlements for. Project IDs are alphanumeric strings, likemy-project. Folder and organization IDs are numeric, like123456789012.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloudalphapamgrantscreate\--entitlement=ENTITLEMENT_ID\--requested-duration="GRANT_DURATIONs"\--justification="JUSTIFICATION"\--location=global\[--additional-email-recipients=EMAIL_ADDRESS_1,EMAIL_ADDRESS_2]\--RESOURCE_TYPE=RESOURCE_ID

Windows (PowerShell)

gcloudalphapamgrantscreate`--entitlement=ENTITLEMENT_ID`--requested-duration="GRANT_DURATIONs"`--justification="JUSTIFICATION"`--location=global`[--additional-email-recipients=EMAIL_ADDRESS_1,EMAIL_ADDRESS_2]`--RESOURCE_TYPE=RESOURCE_ID

Windows (cmd.exe)

gcloudalphapamgrantscreate^--entitlement=ENTITLEMENT_ID^--requested-duration="GRANT_DURATIONs"^--justification="JUSTIFICATION"^--location=global^[--additional-email-recipients=EMAIL_ADDRESS_1,EMAIL_ADDRESS_2]^--RESOURCE_TYPE=RESOURCE_ID

You should receive a response similar to the following:

Created [GRANT_ID].

Request a grant on a child resource of an entitlement

Thegcloud alpha pam grants create command requests a grant.

Before using any of the command data below, make the following replacements:

  • ENTITLEMENT_ID: The entitlement ID to create the grant against.
  • GRANT_DURATION: The requested duration of the grant, in seconds.
  • JUSTIFICATION: The justification for requesting the grant.
  • EMAIL_ADDRESS: Optional. Additional email addresses to notify of the grant request. Google identities associated with approvers are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.
  • RESOURCE_TYPE: Optional. The type of the Google Cloud resources to be granted access to. This is used to customize the scope of the grant to a child resource.
  • RESOURCE_ID: Used withRESOURCE_TYPE. The ID of the Google Cloud project, folder, or organization that you want to manage entitlements for. Project IDs are alphanumeric strings, likemy-project. Folder and organization IDs are numeric, like123456789012.
  • REQUESTED_RESOURCE: Optional. The Google Cloud resources that you want to be granted access to. This is used to customize the scope of the grant to a child resource. Format:RESOURCE_TYPE/RESOURCE_ID. Example:projects/PROJECT_ID,folders/FOLDER_ID, ororganizations/ORGANIZATION_ID.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloudalphapamgrantscreate\--entitlement=ENTITLEMENT_ID\--requested-duration="GRANT_DURATIONs"\--justification="JUSTIFICATION"\--location=global\[--additional-email-recipients=EMAIL_ADDRESS_1,EMAIL_ADDRESS_2]\--RESOURCE_TYPE=RESOURCE_ID\--requested-resources=REQUESTED_RESOURCE

Windows (PowerShell)

gcloudalphapamgrantscreate`--entitlement=ENTITLEMENT_ID`--requested-duration="GRANT_DURATIONs"`--justification="JUSTIFICATION"`--location=global`[--additional-email-recipients=EMAIL_ADDRESS_1,EMAIL_ADDRESS_2]`--RESOURCE_TYPE=RESOURCE_ID`--requested-resources=REQUESTED_RESOURCE

Windows (cmd.exe)

gcloudalphapamgrantscreate^--entitlement=ENTITLEMENT_ID^--requested-duration="GRANT_DURATIONs"^--justification="JUSTIFICATION"^--location=global^[--additional-email-recipients=EMAIL_ADDRESS_1,EMAIL_ADDRESS_2]^--RESOURCE_TYPE=RESOURCE_ID^--requested-resources=REQUESTED_RESOURCE

You should receive a response similar to the following:

Created [GRANT_ID].

Request a grant with fine-grained scope

Thegcloud alpha pam grants create command requests a grant.

Before using any of the command data below, make the following replacements:

  • ENTITLEMENT_ROLE_BINDING_ID: Optional.The role binding ID of the role to be granted from the entitlement.
  • ACCESS_RESTRICTION_NAME: Optional. The resource names to restrict the access to. For information about the format, seeResource name format.
  • ACCESS_RESTRICTION_PREFIX: Optional. The resource name prefixes to restrict the access to. For information about the format, seeResource name format.
  • RESOURCE_TYPE: Optional. The resource type that the entitlement belongs to. Use the valueorganization,folder, orproject.
  • RESOURCE_ID: Used withRESOURCE_TYPE. The ID of the Google Cloud project, folder, or organization that you want to manage entitlements for. Project IDs are alphanumeric strings, likemy-project. Folder and organization IDs are numeric, like123456789012.
  • REQUESTED_RESOURCE_TYPE. Optional. The type of the Google Cloud resources to be granted access to. This is used to customize the scope of the grant to a child resource.
  • REQUESTED_RESOURCE: Optional. The Google Cloud resources that you want to be granted access to. This is used to customize the scope of the grant to a child resource. Format:RESOURCE_TYPE/RESOURCE_ID. Example:projects/PROJECT_ID,folders/FOLDER_ID, ororganizations/ORGANIZATION_ID.

Save the following content in a file calledrequested-scope.yaml:

-gcpIamAccess:resource:REQUESTED_RESOURCEresourceType:REQUESTED_RESOURCE_TYPEroleBindings:-entitlementRoleBindingId:ENTITLEMENT_ROLE_BINDING_ID_1accessRestrictions:resourceNames:-ACCESS_RESTRICTION_NAME_1-ACCESS_RESTRICTION_NAME_2-entitlementRoleBindingId:ENTITLEMENT_ROLE_BINDING_ID_2accessRestrictions:resourceNamePrefixes:-ACCESS_RESTRICTION_PREFIX_1-ACCESS_RESTRICTION_PREFIX_2

Execute the following command:

Linux, macOS, or Cloud Shell

gcloudalphapamgrantscreate\--entitlement=ENTITLEMENT_ID\--requested-duration="GRANT_DURATIONs"\--justification="JUSTIFICATION"\--location=global\[--additional-email-recipients=EMAIL_ADDRESS_1,EMAIL_ADDRESS_2]\--RESOURCE_TYPE=RESOURCE_ID\--requested-access-from-file=requested-scope.yaml

Windows (PowerShell)

gcloudalphapamgrantscreate`--entitlement=ENTITLEMENT_ID`--requested-duration="GRANT_DURATIONs"`--justification="JUSTIFICATION"`--location=global`[--additional-email-recipients=EMAIL_ADDRESS_1,EMAIL_ADDRESS_2]`--RESOURCE_TYPE=RESOURCE_ID`--requested-access-from-file=requested-scope.yaml

Windows (cmd.exe)

gcloudalphapamgrantscreate^--entitlement=ENTITLEMENT_ID^--requested-duration="GRANT_DURATIONs"^--justification="JUSTIFICATION"^--location=global^[--additional-email-recipients=EMAIL_ADDRESS_1,EMAIL_ADDRESS_2]^--RESOURCE_TYPE=RESOURCE_ID^--requested-access-from-file=requested-scope.yaml

You should receive a response similar to the following:

Created [GRANT_ID].

REST

  1. Search for entitlements you're eligible to request.

    The Privileged Access Manager API'ssearchEntitlements method with theGRANT_REQUESTER caller access type searches for entitlements you can request a grant against.

    Before using any of the request data, make the following replacements:

    • SCOPE: The organization, folder, or project that the entitlement is in, in the format oforganizations/ORGANIZATION_ID,folders/FOLDER_ID, orprojects/PROJECT_ID. Project IDs are alphanumeric strings, likemy-project. Folder and organization IDs are numeric, like123456789012.
    • FILTER: Optional. Returns entitlements whose field values match an AIP-160 expression.
    • PAGE_SIZE: Optional. The number of items to return in a response.
    • PAGE_TOKEN: Optional. Which page to start the response from, using a page token returned in a previous response.

    HTTP method and URL:

    GET https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements:search?callerAccessType=GRANT_REQUESTER&filter=FILTER&pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN

    To send your request, expand one of these options:

    curl (Linux, macOS, or Cloud Shell)

    Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

    Execute the following command:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements:search?callerAccessType=GRANT_REQUESTER&filter=FILTER&pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN"

    PowerShell (Windows)

    Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

    Execute the following command:

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements:search?callerAccessType=GRANT_REQUESTER&filter=FILTER&pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" | Select-Object -Expand Content

    APIs Explorer (browser)

    Open themethod reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and clickExecute.

    You should receive a JSON response similar to the following:

    {  "name": "SCOPE/locations/global/operations/OPERATION_ID",  "metadata": {    "@type": "type.googleapis.com/google.cloud.privilegedaccessmanager.v1beta.OperationMetadata",    "createTime": "2024-03-05T03:35:14.596739353Z",    "target": "SCOPE/locations/global/entitlements/ENTITLEMENT_ID",    "verb": "create",    "requestedCancellation": false,    "apiVersion": "v1beta"  },  "done": false}
  2. Request a grant against an entitlement.

    The Privileged Access Manager API'screateGrant method requests a grant.

    Before using any of the request data, make the following replacements:

    • SCOPE: The organization, folder, or project that the entitlement is in, in the format oforganizations/ORGANIZATION_ID,folders/FOLDER_ID, orprojects/PROJECT_ID. Project IDs are alphanumeric strings, likemy-project. Folder and organization IDs are numeric, like123456789012.
    • ENTITLEMENT_ID: The entitlement ID to create the grant against.
    • REQUEST_ID: Optional. Must be a non-zero UUID. If the server receives a request with a request ID, it checks if another request with that ID has already been completed within the last 60 minutes. If so, the new request is ignored.
    • GRANT_DURATION: The requested duration of the grant, in seconds.
    • JUSTIFICATION: The justification for requesting the grant.
    • EMAIL_ADDRESS: Optional. Additional email addresses to notify of the grant request. Google identities associated with approvers are automatically notified. However, you might want to notify a different set of email addresses, especially if you're using Workforce Identity Federation.
    • ENTITLEMENT_ROLE_BINDING_ID: Optional. The role binding ID of the role to be granted from the entitlement.
    • ACCESS_RESTRICTION_NAME: Optional. The resource names to restrict the access to. For information about the format, seeResource name format.
    • ACCESS_RESTRICTION_PREFIX: Optional. The resource name prefixes to restrict the access to. For information about the format, seeResource name format.

    HTTP method and URL:

    POST https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements/ENTITLEMENT_ID/grants?requestId=REQUEST_ID

    Request JSON body:

    {  "requestedDuration": "GRANT_DURATIONs",  "justification": {    "unstructuredJustification": "JUSTIFICATION"  },  "additionalEmailRecipients": [    "EMAIL_ADDRESS_1",    "EMAIL_ADDRESS_2",  ],  "requestedPrivilegedAccess": {    "gcpIamAccess": {      "resourceType": "REQUESTED_RESOURCE_TYPE",      "resource": "REQUESTED_RESOURCE",      "roleBindings": [        {          "entitlementRoleBindingId": "ENTITLEMENT_ROLE_BINDING_ID",          "accessRestrictions": {            "resourceNames": [              "ACCESS_RESTRICTION_NAME"            ],            "resourceNamePrefixes": [              "ACCESS_RESTRICTION_PREFIX"            ],          },        }      ],    }  },}

    To send your request, expand one of these options:

    curl (Linux, macOS, or Cloud Shell)

    Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

    Save the request body in a file namedrequest.json, and execute the following command:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements/ENTITLEMENT_ID/grants?requestId=REQUEST_ID"

    PowerShell (Windows)

    Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

    Save the request body in a file namedrequest.json, and execute the following command:

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements/ENTITLEMENT_ID/grants?requestId=REQUEST_ID" | Select-Object -Expand Content

    APIs Explorer (browser)

    Copy the request body and open themethod reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and clickExecute.

    You should receive a JSON response similar to the following:

    {   "name": "SCOPE/locations/global/entitlements/ENTITLEMENT_ID/grants/GRANT_ID",   "createTime": "2024-03-06T03:08:49.330577625Z",   "updateTime": "2024-03-06T03:08:49.625874598Z",   "requester": "alex@example.com",   "requestedDuration": "3600s",   "justification": {     "unstructuredJustification": "Emergency service for outage"   },   "state": "APPROVAL_AWAITED",   "timeline": {     "events": [       {         "eventTime": "2024-03-06T03:08:49.462765846Z",         "requested": {           "expireTime": "2024-03-07T03:08:49.462765846Z"         }       }     ]   },   "privilegedAccess": {     "gcpIamAccess": {       "resourceType": "cloudresourcemanager.googleapis.com/Project",       "resource": "//cloudresourcemanager.googleapis.com/SCOPE",       "roleBindings": [         {           "role": "roles/storage.admin",           "id": "hwqrt_1",           "conditionExpression": "resource.name == \"//cloudresourcemanager.googleapis.com/SCOPE/buckets/bucket-1\" && resource.name.startsWith(\"//cloudresourcemanager.googleapis.com/SCOPE/compute/vms\")"         }       ]     }   },   "requestedPrivilegedAccess": {     "gcpIamAccess": {       "resourceType": "cloudresourcemanager.googleapis.com/Project",       "resource": "//cloudresourcemanager.googleapis.com/SCOPE",       "roleBindings": [         {           "role": "roles/storage.admin",           "entitlementRoleBindingId": "hwqrt_1",           "accessRestrictions": {             "resourceNames": ["//cloudresourcemanager.googleapis.com/SCOPE/buckets/bucket-1"             ],             "resourceNamePrefixes": [                  "//cloudresourcemanager.googleapis.com/SCOPE/compute/vms"             ]           }         }       ]     }   },   "additionalEmailRecipients": [     "bola@google.com"   ]}

Check your grant request status

Console

  1. Go to thePrivileged Access Manager page.

    Go to Privileged Access Manager

  2. Select the organization, folder, or project that you want to view grants in.

  3. In theGrants tab, clickMy grants.

    Your grant can have one of the following statuses:

    StatusDescription
    ActivatingThe grant is in the process of being activated.
    Activation failedPrivileged Access Manager couldn't grant the roles due to a non-retriable error.
    ActiveThe grant is active and the principal has access to the resources permitted by the roles.
    Approval awaitedThe grant request is waiting on a decision from an approver.
    DeniedThe grant request has been denied by an approver.
    EndedThe grant has ended and the roles have been removed from the principal.
    ExpiredThe grant request has expired, as approval wasn't given within 24 hours.
    RevokedThe grant is revoked, and the principal no longer has access to the resources permitted by the roles.
    RevokingThe grant is in the process of being revoked.
    WithdrawingThe grant is in the process of being withdrawn.
    WithdrawnThe grant is withdrawn, and the principal no longer has access to the resources permitted by the roles.

gcloud

Thegcloud alpha pam grants search command used with thehad-created caller relationship searches for grants you have created. To check their status, look for thestate field in the response.

Before using any of the command data below, make the following replacements:

  • ENTITLEMENT_ID: The ID of the entitlement that the grant belongs to.
  • RESOURCE_TYPE: Optional. The resource type that the entitlement belongs to. Use the valueorganization,folder, orproject.
  • RESOURCE_ID: Used withRESOURCE_TYPE. The ID of the Google Cloud project, folder, or organization that you want to manage entitlements for. Project IDs are alphanumeric strings, likemy-project. Folder and organization IDs are numeric, like123456789012.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloudalphapamgrantssearch\--entitlement=ENTITLEMENT_ID\--caller-relationship=had-created\--location=global\--RESOURCE_TYPE=RESOURCE_ID

Windows (PowerShell)

gcloudalphapamgrantssearch`--entitlement=ENTITLEMENT_ID`--caller-relationship=had-created`--location=global`--RESOURCE_TYPE=RESOURCE_ID

Windows (cmd.exe)

gcloudalphapamgrantssearch^--entitlement=ENTITLEMENT_ID^--caller-relationship=had-created^--location=global^--RESOURCE_TYPE=RESOURCE_ID

You should receive a response similar to the following:

additionalEmailRecipients:- bola@example.comcreateTime: '2024-03-07T00:34:32.557017289Z'justification:  unstructuredJustification: Renaming a file to mitigate issue #312name:SCOPE/locations/global/entitlements/ENTITLEMENT_ID/grants/GRANT_IDprivilegedAccess:  gcpIamAccess:    resource: //cloudresourcemanager.googleapis.com/RESOURCE_TYPE/RESOURCE_ID    resourceType: cloudresourcemanager.googleapis.com/Project    roleBindings:    - role: roles/storage.admin      id: hwqrt_1      conditionExpression: resource.name == "//cloudresourcemanager.googleapis.com/RESOURCE_TYPE/RESOURCE_ID/buckets/bucket-1" && resource.name.startsWith("//cloudresourcemanager.googleapis.com/RESOURCE_TYPE/RESOURCE_ID/compute/vms")requestedPrivilegedAccess:  gcpIamAccess:    resource: //cloudresourcemanager.googleapis.com/RESOURCE_TYPE/RESOURCE_ID    resourceType: cloudresourcemanager.googleapis.com/Project    roleBindings:    - role: roles/storage.admin      entitlementRoleBindingId: hwqrt_1      accessRestrictions:        resourceNames:        - //cloudresourcemanager.googleapis.com/RESOURCE_TYPE/RESOURCE_ID/buckets/bucket-1        resourceNamePrefixes:        - //cloudresourcemanager.googleapis.com/RESOURCE_TYPE/RESOURCE_ID/compute/vmsrequestedDuration: 3600srequester: cruz@example.comstate: DENIEDtimeline:  events:  - eventTime: '2024-03-07T00:34:32.793769042Z'    requested:      expireTime: '2024-03-08T00:34:32.793769042Z'  - denied:      actor: alex@example.com      reason: Issue has already been resolved    eventTime: '2024-03-07T00:36:08.309116203Z'updateTime: '2024-03-07T00:34:32.926967128Z'

Grants can have the following statuses:

StatusDescription
ACTIVATINGThe grant is in the process of being activated.
ACTIVATION_FAILEDPrivileged Access Manager couldn't grant the roles due to a non-retriable error.
ACTIVEThe grant is active and the principal has access to the resources permitted by the roles.
APPROVAL_AWAITEDThe grant request is waiting on a decision from an approver.
DENIEDThe grant request has been denied by an approver.
ENDEDThe grant has ended and the roles have been removed from the principal.
EXPIREDThe grant request has expired, as approval wasn't given within 24 hours.
REVOKEDThe grant is revoked, and the principal no longer has access to the resources permitted by the roles.
REVOKINGThe grant is in the process of being revoked.
WITHDRAWINGThe grant is in the process of being withdrawn.
WITHDRAWNThe grant is withdrawn, and the principal no longer has access to the resources permitted by the roles.

REST

The Privileged Access Manager API'ssearchGrants method used with theHAD_CREATED caller relationship searches for grants you have created. To check their status, look for thestate field in the response.

Before using any of the request data, make the following replacements:

  • SCOPE: The organization, folder, or project that the entitlement is in, in the format oforganizations/ORGANIZATION_ID,folders/FOLDER_ID, orprojects/PROJECT_ID. Project IDs are alphanumeric strings, likemy-project. Folder and organization IDs are numeric, like123456789012.
  • ENTITLEMENT_ID: The ID of the entitlement that the grant belongs to.
  • FILTER: Optional. Returns grants whose field values match an AIP-160 expression.
  • PAGE_SIZE: Optional. The number of items to return in a response.
  • PAGE_TOKEN: Optional. Which page to start the response from, using a page token returned in a previous response.

HTTP method and URL:

GET https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements/ENTITLEMENT_ID/grants:search?callerRelationship=HAD_CREATED&filter=FILTER&pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Execute the following command:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements/ENTITLEMENT_ID/grants:search?callerRelationship=HAD_CREATED&filter=FILTER&pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://privilegedaccessmanager.googleapis.com/v1beta/SCOPE/locations/global/entitlements/ENTITLEMENT_ID/grants:search?callerRelationship=HAD_CREATED&filter=FILTER&pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" | Select-Object -Expand Content

APIs Explorer (browser)

Open themethod reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and clickExecute.

You should receive a JSON response similar to the following:

{  "grants": [    {      "name": "SCOPE/locations/global/entitlements/ENTITLEMENT_ID/grants/GRANT_ID",      "createTime": "2024-03-06T03:08:49.330577625Z",      "updateTime": "2024-03-06T03:08:49.625874598Z",      "requester": "alex@example.com",      "requestedDuration": "3600s",      "justification": {        "unstructuredJustification": "Emergency service for outage"      },      "state": "APPROVAL_AWAITED",      "timeline": {        "events": [          {            "eventTime": "2024-03-06T03:08:49.462765846Z",            "requested": {              "expireTime": "2024-03-07T03:08:49.462765846Z"            }          }        ]      },      "privilegedAccess": {        "gcpIamAccess": {          "resourceType": "cloudresourcemanager.googleapis.com/Project",          "resource": "//cloudresourcemanager.googleapis.com/SCOPE",          "roleBindings": [            {              "role": "roles/storage.admin",              "id": "hwqrt_1",              "conditionExpression": "resource.name == \"//cloudresourcemanager.googleapis.com/SCOPE/buckets/bucket-1\" && resource.name.startsWith(\"//cloudresourcemanager.googleapis.com/SCOPE/compute/vms\")"              "conditionExpression": "resource.name == \"//cloudresourcemanager.googleapis.com/SCOPE/buckets/bucket-1\" && resource.name.startsWith(\"//cloudresourcemanager.googleapis.com/SCOPE/compute/vms\")"            }          ]        }      },      "requestedPrivilegedAccess": {        "gcpIamAccess": {          "resourceType": "cloudresourcemanager.googleapis.com/Project",          "resource": "//cloudresourcemanager.googleapis.com/SCOPE",          "roleBindings": [            {              "role": "roles/storage.admin",              "entitlementRoleBindingId": "hwqrt_1",              "accessRestrictions": {                "resourceNames": ["//cloudresourcemanager.googleapis.com/SCOPE/buckets/bucket-1"                ],                "resourceNamePrefixes": ["//cloudresourcemanager.googleapis.com/SCOPE/compute/vms"                ]              }            }          ]        }      },      "additionalEmailRecipients": [        "bola@google.com"      ]    }  ]}

Grant statuses are detailed in the following table.

StatusDescription
ACTIVATINGThe grant is in the process of being activated.
ACTIVATION_FAILEDPrivileged Access Manager couldn't grant the roles due to a non-retriable error.
ACTIVEThe grant is active and the principal has access to the resources permitted by the roles.
APPROVAL_AWAITEDThe grant request is waiting on a decision from an approver.
DENIEDThe grant request has been denied by an approver.
ENDEDThe grant has ended and the roles have been removed from the principal.
EXPIREDThe grant request has expired, as approval wasn't given within 24 hours.
REVOKEDThe grant is revoked, and the principal no longer has access to the resources permitted by the roles.
REVOKINGThe grant is in the process of being revoked.
WITHDRAWINGThe grant is in the process of being withdrawn.
WITHDRAWNThe grant is withdrawn, and the principal no longer has access to the resources permitted by the roles.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.