# REST Resource: projects.locations.entitlements

- [Resource: Entitlement](https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/projects.locations.entitlements#Entitlement)
  - [JSON representation](https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/projects.locations.entitlements#Entitlement.SCHEMA_REPRESENTATION)
- [Methods](https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/projects.locations.entitlements#METHODS_SUMMARY)

## Resource: Entitlement

An entitlement defines the eligibility of a set of users to obtain predefined access for some time possibly after going through an approval workflow.

| JSON representation |
|---|
| ``` { "name": string, "createTime": string, "updateTime": string, "eligibleUsers": [ { object (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/folders.locations.entitlements#Entitlement.AccessControlEntry`) } ], "approvalWorkflow": { object (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/folders.locations.entitlements#Entitlement.ApprovalWorkflow`) }, "privilegedAccess": { object (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/PrivilegedAccess`) }, "maxRequestDuration": string, "state": enum (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/folders.locations.entitlements#Entitlement.State`), "requesterJustificationConfig": { object (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/folders.locations.entitlements#Entitlement.RequesterJustificationConfig`) }, "additionalNotificationTargets": { object (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/folders.locations.entitlements#Entitlement.AdditionalNotificationTargets`) }, "etag": string } ``` |

| Fields ||
|---|---|
| `name` | `string` Identifier. Name of the entitlement. Possible formats: - `organizations/{organization-number}/locations/{region}/entitlements/{entitlement-id}` - `folders/{folder-number}/locations/{region}/entitlements/{entitlement-id}` - `projects/{project-id|project-number}/locations/{region}/entitlements/{entitlement-id}` |
| `createTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. Create time stamp. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `updateTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. Update time stamp. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `eligibleUsers[]` | ``object (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/folders.locations.entitlements#Entitlement.AccessControlEntry`)`` Optional. Who can create grants using this entitlement. This list should contain at most one entry. |
| `approvalWorkflow` | ``object (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/folders.locations.entitlements#Entitlement.ApprovalWorkflow`)`` Optional. The approvals needed before access are granted to a requester. No approvals are needed if this field is null. |
| `privilegedAccess` | ``object (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/PrivilegedAccess`)`` Required. The access granted to a requester on successful approval. |
| `maxRequestDuration` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` Required. The maximum amount of time that access is granted for a request. A requester can ask for a shorter duration but never a longer one. The supported range is between 30 minutes and 168 hours (7 days). A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| `state` | ``enum (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/folders.locations.entitlements#Entitlement.State`)`` Output only. Current state of this entitlement. |
| `requesterJustificationConfig` | ``object (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/folders.locations.entitlements#Entitlement.RequesterJustificationConfig`)`` Required. The manner in which the requester should provide a justification for requesting access. |
| `additionalNotificationTargets` | ``object (`https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/folders.locations.entitlements#Entitlement.AdditionalNotificationTargets`)`` Optional. Additional email addresses to be notified based on actions taken. |
| `etag` | `string` An `etag` is used for optimistic concurrency control as a way to prevent simultaneous updates to the same entitlement. An `etag` is returned in the response to `entitlements.get` and the caller should put the `etag` in the request to `entitlements.patch` so that their change is applied on the same version. If this field is omitted or if there is a mismatch while updating an entitlement, then the server rejects the request. |

| ## Methods ||
|---|---|
| ### `https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/projects.locations.entitlements/create` | Creates a new entitlement in a given project, folder, organization, and in a given location. |
| ### `https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/projects.locations.entitlements/delete` | Deletes a single entitlement. |
| ### `https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/projects.locations.entitlements/get` | Gets details of a single entitlement. |
| ### `https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/projects.locations.entitlements/list` | Lists the entitlements in a given project, folder, organization, and in a given location. |
| ### `https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/projects.locations.entitlements/patch` | Updates the entitlement specified in the request. |
| ### `https://docs.cloud.google.com/iam/docs/reference/pam/rest/v1beta/projects.locations.entitlements/search` | `SearchEntitlements` returns entitlements on which the caller has the specified access. |