Docs

Query grants

POST
/grants/query

Returns the collaboration grants of a project, paginated with a cursor. Only unrevoked grants this API manages are listed (user or team bound to viewer, editor, or admin), including expired grants so a client can DELETE before re-granting. Project-secret setup (sk_proj) and owning-team (relation=team) rows are not returned. Grants are not in resource_scope_index; project scope is required on the query (same as get). Requires project.read. expand: ["principal"] adds envelope fields on user / team and additionally requires user.read and team.read for project secrets (documented on the expand enum; those scopes cannot be ANDed onto this security block because they are body-conditional). A user-bound Console session that already passed the project Check may expand without those scopes.

Accepts either a project secret (oauth2) or a user-bound Console session cookie (sessionCookie). Cookie-authenticated requests follow the scheme's CSRF rules (sessionCookie).

Authorization

headerAuthorizationBearer <token>

Scope: project.read

Query Parameters

project_id*string

The unique identifier of the project

Match^[a-zA-Z0-9_-]+$

Request Body

Request to query the grants of a project.

application/json
  1. body

Request to query the grants of a project.

limit?limit
Range1 <= value <= 100
Default20
page_token?|

Token to retrieve the next page of results. Must be sent with the same sorting as the request that issued the token. Omitting sorting reuses the default sort and only succeeds when that default matches the token.

expand?array<>

Extra principal fields to add onto each grant's user or team (ADR 059 grant exception). Omit it and those objects stay refs. An unrecognised value is rejected.

sorting?
filter?array<>

Filter criteria for querying grants. Combined with AND.

Response Body

The list of grants was returned successfully.

application/json
  1. response

Paginated list of grants.

grants*array<>
next_page_token?|

Token to pass as page_token in the next request to fetch the following page. Absent when there are no more results. The follow-up request must repeat the same sorting that produced this token (omit only when both pages use the default).

Example Request
import { configureZitadel, getApi } from "@zitadel/api/config";// In the browser, through the SDK proxy: the session cookie authenticates the call.const client = getApi(configureZitadel({ projectId: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" }));const grants = await client.queryGrants({}, { project_id: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" });
Example Response
{  "grants": [    {      "id": "string",      "project_id": "string",      "object_type": "project",      "relation": "viewer",      "created_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z",      "user": {        "user_id": "string",        "identifier": "string",        "identifier_property": "string",        "display": "string",        "schema": "string",        "attributes": {},        "metadata": {          "created_at": "2019-08-24T14:15:22Z",          "updated_at": "2019-08-24T14:15:22Z",          "status": "active",          "lifecycle_owner_team_id": "string",          "lifecycle_owner_team": {            "id": "string",            "name": "string",            "status": "active",            "created_at": "2019-08-24T14:15:22Z",            "updated_at": "2019-08-24T14:15:22Z"          }        }      },      "team": {        "team_id": "string",        "name": "string",        "status": "active",        "created_at": "2019-08-24T14:15:22Z",        "updated_at": "2019-08-24T14:15:22Z"      }    }  ],  "next_page_token": "string"}

Was this helpful?