Skip to main content

Search User Grants​

Returns a list of user grants that match the search queries. User grants are the roles users have for a specific project and organization.

Header Parameters
  • x-zitadel-orgid string

    The default is always the organization of the requesting user. If you like to get/set a result of another organization include the header. Make sure the user has permission to access the requested data.

Request Body required
  • query object

    Object unspecific list filters like offset, limit and asc/desc.

  • offset uint64
  • limit int64

    Maximum amount of events returned. The default is set to 1000 in https://github.com/zitadel/zitadel/blob/new-eventstore/cmd/zitadel/startup.yaml. If the limit exceeds the maximum configured ZITADEL will throw an error. If no limit is present the default is taken.

  • asc boolean

    default is descending

  • queries object[]
  • Array [
  • projectIdQuery object
  • projectId string
  • userIdQuery object
  • userId string
  • withGrantedQuery object
  • withGranted boolean
  • roleKeyQuery object
  • roleKey string
  • method string

    Possible values: [TEXT_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    defines which text equality method is used

  • projectGrantIdQuery object
  • projectGrantId string
  • userNameQuery object
  • userName string
  • method string

    Possible values: [TEXT_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    defines which text equality method is used

  • firstNameQuery object
  • firstName string
  • method string

    Possible values: [TEXT_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    defines which text equality method is used

  • lastNameQuery object
  • lastName string
  • method string

    Possible values: [TEXT_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    defines which text equality method is used

  • emailQuery object
  • email string
  • method string

    Possible values: [TEXT_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    defines which text equality method is used

  • orgNameQuery object
  • orgName string
  • method string

    Possible values: [TEXT_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    defines which text equality method is used

  • orgDomainQuery object
  • orgDomain string
  • method string

    Possible values: [TEXT_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    defines which text equality method is used

  • projectNameQuery object
  • projectName string
  • method string

    Possible values: [TEXT_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

  • displayNameQuery object
  • displayName string

    display name of a user

  • method string

    Possible values: [TEXT_QUERY_METHOD_EQUALS, TEXT_QUERY_METHOD_EQUALS_IGNORE_CASE, TEXT_QUERY_METHOD_STARTS_WITH, TEXT_QUERY_METHOD_STARTS_WITH_IGNORE_CASE, TEXT_QUERY_METHOD_CONTAINS, TEXT_QUERY_METHOD_CONTAINS_IGNORE_CASE, TEXT_QUERY_METHOD_ENDS_WITH, TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE]

    Default value: TEXT_QUERY_METHOD_EQUALS

    defines which equality method is used

  • userTypeQuery object
  • type string

    Possible values: [TYPE_UNSPECIFIED, TYPE_HUMAN, TYPE_MACHINE]

    Default value: TYPE_UNSPECIFIED

    type of user

  • ]
Responses

A successful response.

Schema
  • details object
  • totalResult uint64
  • processedSequence uint64
  • viewTimestamp date-time

    the last time the view got updated

  • result object[]
  • Array [
  • id string
  • details object
  • sequence uint64

    on read: the sequence of the last event reduced by the projection

    on manipulation: the timestamp of the event(s) added by the manipulation

  • creationDate date-time

    on read: the timestamp of the first event of the object

    on create: the timestamp of the event(s) added by the manipulation

  • changeDate date-time

    on read: the timestamp of the last event reduced by the projection

    on manipulation: the

  • resourceOwner resource_owner is the organization an object belongs to
  • roleKeys string[]
  • state string

    Possible values: [USER_GRANT_STATE_UNSPECIFIED, USER_GRANT_STATE_ACTIVE, USER_GRANT_STATE_INACTIVE]

    Default value: USER_GRANT_STATE_UNSPECIFIED

    current state of the user

  • userId string
  • userName string
  • firstName string
  • lastName string
  • email string

    email address of the user. (spec: https://tools.ietf.org/html/rfc2822#section-3.4.1)

  • displayName string

    display name of the user

  • orgId string
  • orgName string
  • orgDomain string
  • projectId string
  • projectName string
  • projectGrantId string
  • avatarUrl string

    avatar URL of the user

  • preferredLoginName string
  • userType string

    Possible values: [TYPE_UNSPECIFIED, TYPE_HUMAN, TYPE_MACHINE]

    Default value: TYPE_UNSPECIFIED

    type of the user (human / machine)

  • ]
POST /users/grants/_search

Authorization

type: oauth2flow: authorizationCodescopes: openid,urn:zitadel:iam:org:project:id:zitadel:aud

Request

Base URL
https://$ZITADEL_DOMAIN/management/v1
Bearer Token
x-zitadel-orgid — header
Content-Type
Body required
{

  "query": {

    "offset": "0",

    "limit": 100,

    "asc": true

  },

  "queries": [

    {

      "projectIdQuery": {

        "projectId": "69629023906488334"

      },

      "userIdQuery": {

        "userId": "69629023906488334"

      },

      "withGrantedQuery": {

        "withGranted": true

      },

      "roleKeyQuery": {

        "roleKey": "role.super.man",

        "method": "TEXT_QUERY_METHOD_EQUALS"

      },

      "projectGrantIdQuery": {

        "projectGrantId": "69629023906488334"

      },

      "userNameQuery": {

        "userName": "gigi-giraffe",

        "method": "TEXT_QUERY_METHOD_EQUALS"

      },

      "firstNameQuery": {

        "firstName": "Gigi",

        "method": "TEXT_QUERY_METHOD_EQUALS"

      },

      "lastNameQuery": {

        "lastName": "Giraffe",

        "method": "TEXT_QUERY_METHOD_EQUALS"

      },

      "emailQuery": {

        "email": "gigi@zitadel.com",

        "method": "TEXT_QUERY_METHOD_EQUALS"

      },

      "orgNameQuery": {

        "orgName": "cao",

        "method": "TEXT_QUERY_METHOD_EQUALS"

      },

      "orgDomainQuery": {

        "orgDomain": "OS AG",

        "method": "TEXT_QUERY_METHOD_EQUALS"

      },

      "projectNameQuery": {

        "projectName": "ITADE",

        "method": 3

      },

      "displayNameQuery": {

        "displayName": "Gigi Giraffe",

        "method": "TEXT_QUERY_METHOD_EQUALS"

      },

      "userTypeQuery": {

        "type": "TYPE_HUMAN"

      }

    }

  ]

}
Accept
curl -L -X POST 'https://$ZITADEL_DOMAIN/management/v1/users/grants/_search' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "query": {
    "offset": "0",
    "limit": 100,
    "asc": true
  },
  "queries": [
    {
      "projectIdQuery": {
        "projectId": "69629023906488334"
      },
      "userIdQuery": {
        "userId": "69629023906488334"
      },
      "withGrantedQuery": {
        "withGranted": true
      },
      "roleKeyQuery": {
        "roleKey": "role.super.man",
        "method": "TEXT_QUERY_METHOD_EQUALS"
      },
      "projectGrantIdQuery": {
        "projectGrantId": "69629023906488334"
      },
      "userNameQuery": {
        "userName": "gigi-giraffe",
        "method": "TEXT_QUERY_METHOD_EQUALS"
      },
      "firstNameQuery": {
        "firstName": "Gigi",
        "method": "TEXT_QUERY_METHOD_EQUALS"
      },
      "lastNameQuery": {
        "lastName": "Giraffe",
        "method": "TEXT_QUERY_METHOD_EQUALS"
      },
      "emailQuery": {
        "email": "gigi@zitadel.com",
        "method": "TEXT_QUERY_METHOD_EQUALS"
      },
      "orgNameQuery": {
        "orgName": "cao",
        "method": "TEXT_QUERY_METHOD_EQUALS"
      },
      "orgDomainQuery": {
        "orgDomain": "OS AG",
        "method": "TEXT_QUERY_METHOD_EQUALS"
      },
      "projectNameQuery": {
        "projectName": "ITADE",
        "method": 3
      },
      "displayNameQuery": {
        "displayName": "Gigi Giraffe",
        "method": "TEXT_QUERY_METHOD_EQUALS"
      },
      "userTypeQuery": {
        "type": "TYPE_HUMAN"
      }
    }
  ]
}'