Docs

Get grant

GET
/grants/{id}

Loads a grant by (project_id, id) that this API manages (user or team bound to viewer, editor, or admin) and that has not been revoked. "Active" here means not revoked: expired grants stay visible so the client can DELETE before re-granting the same binding. Authorization still ignores expired grants. Grants are not registered in resource_scope_index; project scope is required on the query (same as events). Misses, revoked rows, project-secret setup (sk_proj), owning-team (relation=team) rows, and cross-project ids return 404. expand=principal adds envelope fields on user or team and requires user.read and team.read in addition to project.read for project secrets. 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

Path Parameters

id*string

Managed assignment id (asgn_<opaque>).

Query Parameters

project_id*string

The unique identifier of the project

Match^[a-zA-Z0-9_-]+$
expand?array<>

Extra principal fields to add onto user or team. Same enum and user.read + team.read gate as POST /grants/query.

Response Body

The grant.

application/json
  1. response

A collaboration grant binding a user or a team to a project relation. Discriminate on which of user or team is present. Those objects are always refs (user_id / team_id); expand adds extra fields on the same object rather than a sibling.

id*string

Managed assignment id (asgn_<opaque>).

project_id*string

Project this grant is scoped to.

object_type*"project"

Catalog object type. Always project for this API.

Value in"project"
relation*string

Catalog relation on the project.

Value in"viewer""editor""admin"
created_at*string

When the grant was created.

Formatdate-time
expires_at?|

When the grant expires. Null when it does not expire. GET still returns expired unrevoked grants; authorization ignores them.

user?

Present on a user grant. Omit on a team grant. Always a user-ref (user_id); expand adds envelope fields on this same object.

team?

Present on a team grant. Omit on a user grant. Always a team-ref (team_id); expand adds envelope fields on this same object.

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 grant = await client.getGrant("asgn_01KWH9D4R2V7F0N9WD3P2E4YM8", { project_id: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" });
Example Response
{  "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"  }}

Was this helpful?