Search User Grants

POST /users/grants/_search

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

Request

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.

application/json
application/grpc
application/grpc-web+proto

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

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

firstNameQuery

object

firstName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

lastNameQuery

object

lastName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

emailQuery

object

email string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

orgNameQuery

object

orgName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

orgDomainQuery

object

orgDomain string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

projectNameQuery

object

projectName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

displayNameQuery

object

displayName string

display name of a user

method string

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

]

Body

required

query

object

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

offset uint64

limit int64

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

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

projectGrantIdQuery

object

projectGrantId string

userNameQuery

object

userName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

firstNameQuery

object

firstName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

lastNameQuery

object

lastName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

emailQuery

object

email string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

orgNameQuery

object

orgName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

orgDomainQuery

object

orgDomain string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

projectNameQuery

object

projectName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

displayNameQuery

object

displayName string

display name of a user

method string

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

]

Body

required

query

object

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

offset uint64

limit int64

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

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

projectGrantIdQuery

object

projectGrantId string

userNameQuery

object

userName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

firstNameQuery

object

firstName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

lastNameQuery

object

lastName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

emailQuery

object

email string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

orgNameQuery

object

orgName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

orgDomainQuery

object

orgDomain string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

defines which text equality method is used

projectNameQuery

object

projectName string

method string

Default value: TEXT_QUERY_METHOD_EQUALS

displayNameQuery

object

displayName string

display name of a user

method string

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

200
default

A successful response.

application/json
application/grpc
application/grpc-web+proto

Schema
Example (from schema)

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 (string)

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)

grantedOrgId string

grantedOrgName string

grantedOrgDomain string

]

{
  "details": {
    "totalResult": "2",
    "processedSequence": "267831",
    "viewTimestamp": "2024-11-15T21:46:16.369Z"
  },
  "result": [
    {
      "id": "69629023906488334",
      "details": {
        "sequence": "2",
        "creationDate": "2024-11-15T21:46:16.369Z",
        "changeDate": "2024-11-15T21:46:16.369Z",
        "resourceOwner": "69629023906488334"
      },
      "roleKeys": [
        "role.super.man"
      ],
      "state": "USER_GRANT_STATE_UNSPECIFIED",
      "userId": "69629023906488334",
      "userName": "gigi-giraffe",
      "firstName": "Gigi",
      "lastName": "Giraffe",
      "email": "gigi@zitadel.com",
      "displayName": "Gigi Giraffe",
      "orgId": "69629023906488334",
      "orgName": "ZITADEL",
      "orgDomain": "zitadel.cloud",
      "projectId": "69629023906488334",
      "projectName": "ZITADEL",
      "projectGrantId": "69629023906488334",
      "avatarUrl": "{your-domain}/assets/v1/avatar-32432jkh4kj32",
      "preferredLoginName": "gigi@zitadel.com",
      "userType": "TYPE_UNSPECIFIED",
      "grantedOrgId": "69629023906488334",
      "grantedOrgName": "ZITADEL",
      "grantedOrgDomain": "zitadel.cloud"
    }
  ]
}

Schema
Example (from schema)

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 (string)

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)

grantedOrgId string

grantedOrgName string

grantedOrgDomain string

]

{
  "details": {
    "totalResult": "2",
    "processedSequence": "267831",
    "viewTimestamp": "2024-11-15T21:46:16.370Z"
  },
  "result": [
    {
      "id": "69629023906488334",
      "details": {
        "sequence": "2",
        "creationDate": "2024-11-15T21:46:16.370Z",
        "changeDate": "2024-11-15T21:46:16.370Z",
        "resourceOwner": "69629023906488334"
      },
      "roleKeys": [
        "role.super.man"
      ],
      "state": "USER_GRANT_STATE_UNSPECIFIED",
      "userId": "69629023906488334",
      "userName": "gigi-giraffe",
      "firstName": "Gigi",
      "lastName": "Giraffe",
      "email": "gigi@zitadel.com",
      "displayName": "Gigi Giraffe",
      "orgId": "69629023906488334",
      "orgName": "ZITADEL",
      "orgDomain": "zitadel.cloud",
      "projectId": "69629023906488334",
      "projectName": "ZITADEL",
      "projectGrantId": "69629023906488334",
      "avatarUrl": "{your-domain}/assets/v1/avatar-32432jkh4kj32",
      "preferredLoginName": "gigi@zitadel.com",
      "userType": "TYPE_UNSPECIFIED",
      "grantedOrgId": "69629023906488334",
      "grantedOrgName": "ZITADEL",
      "grantedOrgDomain": "zitadel.cloud"
    }
  ]
}

Schema
Example (from schema)

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 (string)

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)

grantedOrgId string

grantedOrgName string

grantedOrgDomain string

]

{
  "details": {
    "totalResult": "2",
    "processedSequence": "267831",
    "viewTimestamp": "2024-11-15T21:46:16.371Z"
  },
  "result": [
    {
      "id": "69629023906488334",
      "details": {
        "sequence": "2",
        "creationDate": "2024-11-15T21:46:16.371Z",
        "changeDate": "2024-11-15T21:46:16.371Z",
        "resourceOwner": "69629023906488334"
      },
      "roleKeys": [
        "role.super.man"
      ],
      "state": "USER_GRANT_STATE_UNSPECIFIED",
      "userId": "69629023906488334",
      "userName": "gigi-giraffe",
      "firstName": "Gigi",
      "lastName": "Giraffe",
      "email": "gigi@zitadel.com",
      "displayName": "Gigi Giraffe",
      "orgId": "69629023906488334",
      "orgName": "ZITADEL",
      "orgDomain": "zitadel.cloud",
      "projectId": "69629023906488334",
      "projectName": "ZITADEL",
      "projectGrantId": "69629023906488334",
      "avatarUrl": "{your-domain}/assets/v1/avatar-32432jkh4kj32",
      "preferredLoginName": "gigi@zitadel.com",
      "userType": "TYPE_UNSPECIFIED",
      "grantedOrgId": "69629023906488334",
      "grantedOrgName": "ZITADEL",
      "grantedOrgDomain": "zitadel.cloud"
    }
  ]
}

An unexpected error response.

application/json
application/grpc
application/grpc-web+proto

Schema
Example (from schema)

Schema

code int32

message string

details

object[]

Array [

@type string

]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Schema
Example (from schema)

Schema

code int32

message string

details

object[]

Array [

@type string

]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Schema
Example (from schema)

Schema

code int32

message string

details

object[]

Array [

@type string

]

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Search User Grants

/users/grants/_search

Request​

Header Parameters

Body

Body

Body

Responses​

Request

Responses