Test My Permissions

POST

/iam/v1/scopes/{scope_type}/{scope_id}/access/me/permissions:test

curl --request POST \
  --url https://example.com/iam/v1/scopes/example/example/access/me/permissions:test \
  --header 'Content-Type: application/json' \
  --data '{ "scope_type": "example", "scope_id": "example", "permissions": [ "example" ] }'

Answers which of the named candidate permissions the calling principal effectively holds at the requested scope. Same advisory semantics as ListMyEffectivePermissions; a candidate naming no existing permission is rejected as invalid rather than reported as not held.

Parameters

Path Parameters

scope_type

required

string

The scope type: PLATFORM, ORGANISATION, WORKSPACE, or GROUP.

This MUST remain a string and MUST NOT become a proto enum, for the same reason as on ListMyEffectivePermissionsRequest.

scope_id

required

string

The unique identifier of the scope. For the PLATFORM scope this is the zero-UUID sentinel 00000000-0000-0000-0000-000000000000.

Request Body ^required

Media type application/json

TestMyPermissionsRequest

Request message for TestMyPermissions. As with the list request, there is no principal field - me is fixed in the path.

object

scope_type

required

The scope type: PLATFORM, ORGANISATION, WORKSPACE, or GROUP.

This MUST remain a string and MUST NOT become a proto enum, for the same reason as on ListMyEffectivePermissionsRequest.

string

scope_id

required

The unique identifier of the scope. For the PLATFORM scope this is the zero-UUID sentinel 00000000-0000-0000-0000-000000000000.

string

permissions

required

The candidate permission keys to test, each <service>.<resource>.<action>. A candidate naming no existing permission is rejected as invalid - never reported as simply not held.

Array<string>

Example ^generated

{
  "scope_type": "example",
  "scope_id": "example",
  "permissions": [
    "example"
  ]
}

Responses

200

OK

Media type application/json

TestMyPermissionsResponse

Response message for TestMyPermissions.

object

granted

The candidates the caller effectively holds, each with its condition kinds and provenance lineage. A candidate absent here is not held.

Array<object>

One permission the principal effectively holds at the requested scope.

Advisory display data: use it to decide what to show, never as an authorization decision - every action is enforced by the platform when it is attempted. Policy conditions are reported via condition_kinds, never evaluated by this read.

object

permission

The permission key, <service>.<resource>.<action>.

stringOutput only

service

The service facet of the key (e.g. “compute”).

stringOutput only

resource

The resource facet of the key (e.g. “vm”).

stringOutput only

action

The action facet of the key (e.g. “create”).

stringOutput only

condition_kinds

The kinds of condition guarding this permission.

Empty means the permission is held outright - at least one granting binding carries no condition at all. Non-empty means every granting binding is conditional, and these are the kinds involved; CONDITION_KIND_UNKNOWN appears when a condition exists but its definition could not be read.

Reported, never evaluated: the same question asked at any time, from any network, returns the same kinds.

Array<string>Output only

Allowed values: CONDITION_KIND_UNSPECIFIED CONDITION_KIND_SOURCE_IP CONDITION_KIND_TIME_WINDOW CONDITION_KIND_ROLE CONDITION_KIND_LOCATION CONDITION_KIND_UNKNOWN

lineage

Every granting role, most-local first (direct grants before inherited, then by proximity of the origin scope).

Array<object>Output only

One granting role behind an effective permission - the provenance of a grant.

object

role_id

The unique identifier of the granting role.

stringOutput only

role_name

The human-readable name of the granting role.

stringOutput only

origin

Whether the grant was made at the requested scope or inherited from an ancestor.

string format: enum Output only

Allowed values: ROLE_ORIGIN_UNSPECIFIED ROLE_ORIGIN_DIRECT ROLE_ORIGIN_INHERITED

origin_scope_type

The scope type the grant was inherited from; unset when origin is DIRECT.

string format: enum Output only

Allowed values: SCOPE_TYPE_UNSPECIFIED SCOPE_TYPE_WORKSPACE SCOPE_TYPE_GROUP SCOPE_TYPE_ORGANISATION SCOPE_TYPE_PLATFORM

origin_scope_id

The scope id the grant was inherited from; empty when origin is DIRECT.

stringOutput only

conditional

Whether this particular grant only holds under a policy condition.

booleanOutput only

Example

{
  "granted": [
    {
      "condition_kinds": [
        "CONDITION_KIND_UNSPECIFIED"
      ],
      "lineage": [
        {
          "origin": "ROLE_ORIGIN_UNSPECIFIED",
          "origin_scope_type": "SCOPE_TYPE_UNSPECIFIED"
        }
      ]
    }
  ]
}

default

Default error response

Media type application/json

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. 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.

object

code

The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

integer format: int32

message

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][google.rpc.Status.details] field, or localized by the client.

string

details

A list of messages that carry the error details. There is a common set of message types for APIs to use.

Array<object>

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

object

@type

The type of the serialized message.

string

key

additional properties

any

Example ^generated

{
  "code": 1,
  "message": "example",
  "details": [
    {
      "@type": "example"
    }
  ]
}