Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Identity and Access Management (IAM) Policies API
version: v2
description: Generated from Google's published Discovery document for Identity and Access Management (IAM) API (iam v2, revision 20261106). 6 operation(s).
contact:
name: Google
url: https://developers.google.com/
termsOfService: https://developers.google.com/terms
servers:
- url: https://iam.googleapis.com
tags:
- name: Policies
paths:
/v2/policies/{policiesId}/{policiesId1}:
get:
operationId: iam.policies.listPolicies
summary: List policies policies
description: Retrieves the policies of the specified kind that are attached to a resource. The response lists only policy metadata. In particular, policy rules are omitted.
parameters:
- name: policiesId
in: path
required: true
description: Resource name segment (policiesId).
schema:
type: string
- name: policiesId1
in: path
required: true
description: Resource name segment (policiesId1).
schema:
type: string
- name: pageSize
in: query
required: false
description: The maximum number of policies to return. IAM ignores this value and uses the value 1000.
schema:
type: integer
format: int32
- name: pageToken
in: query
required: false
description: A page token received in a ListPoliciesResponse. Provide this token to retrieve the next page.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleIamV2ListPoliciesResponse'
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/cloud-platform
- apiKey: []
tags:
- Policies
post:
operationId: iam.policies.createPolicy
summary: Create policy policies
description: Creates a policy.
parameters:
- name: policiesId
in: path
required: true
description: Resource name segment (policiesId).
schema:
type: string
- name: policiesId1
in: path
required: true
description: Resource name segment (policiesId1).
schema:
type: string
- name: policyId
in: query
required: false
description: The ID to use for this policy, which will become the final component of the policy's resource name. The ID must contain 3 to 63 characters. It can contain lowercase letters and numbers, as well as dashes (`-`) and periods (`.`). The first character must be a lowercase letter.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleIamV2Policy'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleLongrunningOperation'
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/cloud-platform
- apiKey: []
tags:
- Policies
/v2/policies/{policiesId}/{policiesId1}/{policiesId2}:
delete:
operationId: iam.policies.delete
summary: Delete policies
description: Deletes a policy. This action is permanent.
parameters:
- name: policiesId
in: path
required: true
description: Resource name segment (policiesId).
schema:
type: string
- name: policiesId1
in: path
required: true
description: Resource name segment (policiesId1).
schema:
type: string
- name: policiesId2
in: path
required: true
description: Resource name segment (policiesId2).
schema:
type: string
- name: etag
in: query
required: false
description: Optional. The expected `etag` of the policy to delete. If the value does not match the value that is stored in IAM, the request fails with a `409` error code and `ABORTED` status. If you omit this field, the policy is deleted regardless of its current `etag`.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleLongrunningOperation'
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/cloud-platform
- apiKey: []
tags:
- Policies
put:
operationId: iam.policies.update
summary: Update policies
description: 'Updates the specified policy. You can update only the rules and the display name for the policy. To update a policy, you should use a read-modify-write loop: 1. Use GetPolicy to read the current version of the policy. 2. Modify the policy as needed. 3. Use `UpdatePolicy` to write the updated policy. This pattern helps prevent conflicts between concurrent updates.'
parameters:
- name: policiesId
in: path
required: true
description: Resource name segment (policiesId).
schema:
type: string
- name: policiesId1
in: path
required: true
description: Resource name segment (policiesId1).
schema:
type: string
- name: policiesId2
in: path
required: true
description: Resource name segment (policiesId2).
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleIamV2Policy'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleLongrunningOperation'
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/cloud-platform
- apiKey: []
tags:
- Policies
get:
operationId: iam.policies.get
summary: Get policies
description: Gets a policy.
parameters:
- name: policiesId
in: path
required: true
description: Resource name segment (policiesId).
schema:
type: string
- name: policiesId1
in: path
required: true
description: Resource name segment (policiesId1).
schema:
type: string
- name: policiesId2
in: path
required: true
description: Resource name segment (policiesId2).
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleIamV2Policy'
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/cloud-platform
- apiKey: []
tags:
- Policies
/v2/policies/{policiesId}/{policiesId1}/{policiesId2}/operations/{operationsId}:
get:
operationId: iam.policies.operations.get
summary: Get operations
description: Gets the latest state of a long-running operation. Clients can use this method to poll the operation result at intervals as recommended by the API service.
parameters:
- name: policiesId
in: path
required: true
description: Resource name segment (policiesId).
schema:
type: string
- name: policiesId1
in: path
required: true
description: Resource name segment (policiesId1).
schema:
type: string
- name: policiesId2
in: path
required: true
description: Resource name segment (policiesId2).
schema:
type: string
- name: operationsId
in: path
required: true
description: Resource name segment (operationsId).
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleLongrunningOperation'
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/GoogleRpcError'
description: Error response (google.rpc.Status)
security:
- oauth2:
- https://www.googleapis.com/auth/cloud-platform
- apiKey: []
tags:
- Policies
components:
schemas:
GoogleIamV2PolicyRule:
description: A single rule in a `Policy`.
type: object
properties:
description:
type: string
description: A user-specified description of the rule. This value can be up to 256 characters.
denyRule:
$ref: '#/components/schemas/GoogleIamV2DenyRule'
description: A rule for a deny policy.
GoogleTypeExpr:
properties:
expression:
type: string
description: Textual representation of an expression in Common Expression Language syntax.
location:
description: Optional. String indicating the location of the expression for error reporting, e.g. a file name and a position in the file.
type: string
description:
description: Optional. Description of the expression. This is a longer text which describes the expression, e.g. when hovered over it in a UI.
type: string
title:
description: 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.
type: string
type: object
description: 'Represents a textual expression in the Common Expression Language (CEL) syntax. CEL is a C-like expression language. The syntax and semantics of CEL are documented at https://github.com/google/cel-spec. Example (Comparison): title: "Summary size limit" description: "Determines if a summary is less than 100 chars" expression: "document.summary.size() < 100" Example (Equality): title: "Requestor is owner" description: "Determines if requestor is the document owner" expression: "document.owner == request.auth.claims.email" Example (Logic): title: "Public documents" description: "Determine whether the document should be publicly visible" expression: "document.type != ''private'' && document.type != ''internal''" Example (Data Manipulation): title: "Notification string" description: "Create a notification string with a timestamp." expression: "''New message received at '' + string(document.create_time)" The exact variables and functions that may be referenced within an expression are determined by the service that evaluates it. See the service documentation for additional information.'
GoogleRpcStatus:
type: object
description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
properties:
code:
type: integer
description: The status code, which should be an enum value of google.rpc.Code.
format: int32
message:
description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.
type: string
details:
description: A list of messages that carry the error details. There is a common set of message types for APIs to use.
items:
type: object
additionalProperties:
description: Properties of the object. Contains field @type with type URL.
type: array
GoogleIamV2ListPoliciesResponse:
properties:
policies:
description: Metadata for the policies that are attached to the resource.
items:
$ref: '#/components/schemas/GoogleIamV2Policy'
type: array
nextPageToken:
type: string
description: A page token that you can use in a ListPoliciesRequest to retrieve the next page. If this field is omitted, there are no additional pages.
description: Response message for `ListPolicies`.
type: object
GoogleLongrunningOperation:
type: object
properties:
done:
description: If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.
type: boolean
response:
description: The normal, successful response of the operation. If the original method returns no data on success, such as `Delete`, the response is `google.protobuf.Empty`. If the original method is standard `Get`/`Create`/`Update`, the response should be the resource. For other methods, the response should have the type `XxxResponse`, where `Xxx` is the original method name. For example, if the original method name is `TakeSnapshot()`, the inferred response type is `TakeSnapshotResponse`.
type: object
additionalProperties:
description: Properties of the object. Contains field @type with type URL.
name:
description: The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.
type: string
error:
$ref: '#/components/schemas/GoogleRpcStatus'
description: The error result of the operation in case of failure or cancellation.
metadata:
additionalProperties:
description: Properties of the object. Contains field @type with type URL.
type: object
description: Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata. Any method that returns a long-running operation should document the metadata type, if any.
description: This resource represents a long-running operation that is the result of a network API call.
GoogleIamV2DenyRule:
type: object
properties:
deniedPrincipals:
type: array
description: ' The identities that are prevented from using one or more permissions on Google Cloud resources. This field can contain the following values: * `principal://goog/subject/{email_id}`: A specific Google Account. Includes Gmail, Cloud Identity, and Google Workspace user accounts. For example, `principal://goog/subject/alice@example.com`. * `principal://iam.googleapis.com/projects/-/serviceAccounts/{service_account_id}`: A Google Cloud service account. For example, `principal://iam.googleapis.com/projects/-/serviceAccounts/my-service-account@iam.gserviceaccount.com`. * `principalSet://goog/group/{group_id}`: A Google group. For example, `principalSet://goog/group/admins@example.com`. * `principalSet://goog/public:all`: A special identifier that represents any principal that is on the internet, even if they do not have a Google Account or are not logged in. * `principalSet://goog/cloudIdentityCustomerId/{customer_id}`: All of the principals associated with the specified Google Workspace or Cloud Identity customer ID. For example, `principalSet://goog/cloudIdentityCustomerId/C01Abc35`. * `principal://iam.googleapis.com/locations/global/workforcePools/{pool_id}/subject/{subject_attribute_value}`: A single identity in a workforce identity pool. * `principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/group/{group_id}`: All workforce identities in a group. * `principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/attribute.{attribute_name}/{attribute_value}`: All workforce identities with a specific attribute value. * `principalSet://iam.googleapis.com/locations/global/workforcePools/{pool_id}/*`: All identities in a workforce identity pool. * `principal://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/subject/{subject_attribute_value}`: A single identity in a workload identity pool. * `principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/group/{group_id}`: A workload identity pool group. * `principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/attribute.{attribute_name}/{attribute_value}`: All identities in a workload identity pool with a certain attribute. * `principalSet://iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/*`: All identities in a workload identity pool. * `principalSet://cloudresourcemanager.googleapis.com/[projects|folders|organizations]/{project_number|folder_number|org_number}/type/ServiceAccount`: All service accounts grouped under a resource (project, folder, or organization). * `principalSet://cloudresourcemanager.googleapis.com/[projects|folders|organizations]/{project_number|folder_number|org_number}/type/ServiceAgent`: All service agents grouped under a resource (project, folder, or organization). * `deleted:principal://goog/subject/{email_id}?uid={uid}`: A specific Google Account that was deleted recently. For example, `deleted:principal://goog/subject/alice@example.com?uid=1234567890`. If the Google Account is recovered, this identifier reverts to the standard identifier for a Google Account. * `deleted:principalSet://goog/group/{group_id}?uid={uid}`: A Google group that was deleted recently. For example, `deleted:principalSet://goog/group/admins@example.com?uid=1234567890`. If the Google group is restored, this identifier reverts to the standard identifier for a Google group. * `deleted:principal://iam.googleapis.com/projects/-/serviceAccounts/{service_account_id}?uid={uid}`: A Google Cloud service account that was deleted recently. For example, `deleted:principal://iam.googleapis.com/projects/-/serviceAccounts/my-service-account@iam.gserviceaccount.com?uid=1234567890`. If the service account is undeleted, this identifier reverts to the standard identifier for a service account. * `deleted:principal://iam.googleapis.com/locations/global/workforcePools/{pool_id}/subject/{subject_attribute_value}`: Deleted single identity in a workforce identity pool. For example, `deleted:principal://iam.googleapis.com/locations/global/workforcePools/my-pool-id/subject/my-subject-attribute-value`.'
items:
type: string
exceptionPermissions:
description: Specifies the permissions that this rule excludes from the set of denied permissions given by `denied_permissions`. If a permission appears in `denied_permissions` _and_ in `exception_permissions` then it will _not_ be denied. The excluded permissions can be specified using the same syntax as `denied_permissions`.
items:
type: string
type: array
exceptionPrincipals:
items:
type: string
description: The identities that are excluded from the deny rule, even if they are listed in the `denied_principals`. For example, you could add a Google group to the `denied_principals`, then exclude specific users who belong to that group. This field can contain the same values as the `denied_principals` field, excluding `principalSet://goog/public:all`, which represents all users on the internet.
type: array
deniedPermissions:
items:
type: string
type: array
description: The permissions that are explicitly denied by this rule. Each permission uses the format `{service_fqdn}/{resource}.{verb}`, where `{service_fqdn}` is the fully qualified domain name for the service. For example, `iam.googleapis.com/roles.list`.
denialCondition:
$ref: '#/components/schemas/GoogleTypeExpr'
description: The condition that determines whether this deny rule applies to a request. If the condition expression evaluates to `true`, then the deny rule is applied; otherwise, the deny rule is not applied. Each deny rule is evaluated independently. If this deny rule does not apply to a request, other deny rules might still apply. The condition can use CEL functions that evaluate [resource tags](https://cloud.google.com/iam/help/conditions/resource-tags). Other functions and operators are not supported.
description: A deny rule in an IAM deny policy.
GoogleIamV2Policy:
type: object
description: Data for an IAM policy.
properties:
deleteTime:
readOnly: true
description: Output only. The time when the `Policy` was deleted. Empty if the policy is not deleted.
type: string
format: google-datetime
displayName:
description: A user-specified description of the `Policy`. This value can be up to 63 characters.
type: string
uid:
description: Immutable. The globally unique ID of the `Policy`. Assigned automatically when the `Policy` is created.
type: string
rules:
description: A list of rules that specify the behavior of the `Policy`. All of the rules should be of the `kind` specified in the `Policy`.
type: array
items:
$ref: '#/components/schemas/GoogleIamV2PolicyRule'
name:
description: 'Immutable. The resource name of the `Policy`, which must be unique. Format: `policies/{attachment_point}/denypolicies/{policy_id}` The attachment point is identified by its URL-encoded full resource name, which means that the forward-slash character, `/`, must be written as `%2F`. For example, `policies/cloudresourcemanager.googleapis.com%2Fprojects%2Fmy-project/denypolicies/my-deny-policy`. For organizations and folders, use the numeric ID in the full resource name. For projects, requests can use the alphanumeric or the numeric ID. Responses always contain the numeric ID.'
type: string
kind:
type: string
readOnly: true
description: Output only. The kind of the `Policy`. Always contains the value `DenyPolicy`.
etag:
description: An opaque tag that identifies the current version of the `Policy`. IAM uses this value to help manage concurrent updates, so they do not cause one update to be overwritten by another. If this field is present in a CreatePolicyRequest, the value is ignored.
type: string
createTime:
type: string
description: Output only. The time when the `Policy` was created.
readOnly: true
format: google-datetime
annotations:
type: object
description: A key-value map to store arbitrary metadata for the `Policy`. Keys can be up to 63 characters. Values can be up to 255 characters.
additionalProperties:
type: string
updateTime:
description: Output only. The time when the `Policy` was last updated.
format: google-datetime
readOnly: true
type: string
GoogleRpcError:
type: object
description: The error envelope every Google API returns.
properties:
error:
type: object
properties:
code:
type: integer
message:
type: string
status:
type: string
details:
type: array
items:
type: object
securitySchemes:
apiKey:
type: apiKey
in: query
name: key
description: API key; accepted by methods that do not need user data.
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://accounts.google.com/o/oauth2/auth
tokenUrl: https://oauth2.googleapis.com/token
scopes:
https://www.googleapis.com/auth/cloud-platform: See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account.
externalDocs:
url: https://cloud.google.com/iam/
x-provenance:
method: harvested
publisher: Google
source: https://iam.googleapis.com/$discovery/rest?version=v2
note: converted by discovery-to-openapi.py from Google's Discovery document (revision 20261106)