Grants

The permissions model. A grant gives a principal (user or email) a role (viewer / commenter / editor) on a deck or folder; folder grants cascade. Creating a grant upserts on (principal, resource).

Related guides: Sharing & permissions

Attributes

idstringrequired
objectstringrequired
principal_typestringrequired
Possible values: user, email, group, org
principalstringrequired
resource_typestringrequired
Possible values: deck, folder
resourcestringrequired
rolestringrequired
Possible values: viewer, commenter, editor
created_bystring | nullrequired
created_attimestamprequired
updated_attimestamprequired

Endpoints

GET/v1/grants
POST/v1/grants
GET/v1/grants/{id}
DELETE/v1/grants/{id}

The Grant object

{
  "id": "grt_5d2a…",
  "object": "grant",
  "principal_type": "user",
  "principal": "alice@acme.com",
  "resource_type": "deck",
  "resource": "deck_2a9f…",
  "role": "viewer",
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

List grants

GET/v1/grants

Lists access grants in the active org. Filter by `resource`/`resource_type` or `principal`.

Requires an API key (bearer), scoped to the active org.

Query parameters

limitintegeroptionaldefault 201–100
cursorstringoptional
orderstringoptionaldefault "created_at.desc"
Possible values: created_at.desc, created_at.asc
resource_typestringoptional
Possible values: deck, folder
resourcestringoptional
principalstringoptional

Returns

200A page of grants.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza grants list

GET /v1/grants

curl https://api.renza.io/v1/grants \
  -H "Authorization: Bearer $RENZA_API_KEY"

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const page = await renza.grants.list();

Response 200

{
  "object": "list",
  "url": "/v1/decks",
  "data": [
    {
      "id": "grt_5d2a…",
      "object": "grant",
      "principal_type": "user",
      "principal": "alice@acme.com",
      "resource_type": "deck",
      "resource": "deck_2a9f…",
      "role": "viewer",
      "created_at": "2026-06-19T10:30:00.000Z",
      "updated_at": "2026-06-19T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Grant access

POST/v1/grants

Grants a principal a role on a resource (folder grants cascade to the subtree). If a grant for that principal+resource already exists, its role is updated (200); otherwise a grant is created (201).

Requires an API key (bearer), scoped to the active org. Supports idempotency keys.

Body parameters

principal_typestringrequired
Possible values: user, email, group, org
principalstringrequiredmax 320 chars
User id, email, or group id.
resource_typestringrequired
Possible values: deck, folder
resourcestringrequired
rolestringrequired
Possible values: viewer, commenter, editor

Returns

200The updated grant.
201The new grant.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza grants create deck_2a9f… alice@acme.com \
  --principal-type email \
  --resource-type deck \
  --role commenter

POST /v1/grants

curl https://api.renza.io/v1/grants \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "principal_type": "email",
  "principal": "alice@acme.com",
  "resource_type": "deck",
  "resource": "deck_2a9f…",
  "role": "commenter"
}'

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const grant = await renza.grants.create({
  principal_type: "email",
  principal: "alice@acme.com",
  resource_type: "deck",
  resource: "deck_2a9f…",
  role: "commenter",
});

Response 200

{
  "id": "grt_5d2a…",
  "object": "grant",
  "principal_type": "user",
  "principal": "alice@acme.com",
  "resource_type": "deck",
  "resource": "deck_2a9f…",
  "role": "viewer",
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

Retrieve a grant

GET/v1/grants/{id}

Fetches a single access grant by id within the active org.

Requires an API key (bearer), scoped to the active org.

Path parameters

idstringrequired

Returns

200The grant.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza grants get grt_5d2a…

GET /v1/grants/{id}

curl https://api.renza.io/v1/grants/grt_5d2a… \
  -H "Authorization: Bearer $RENZA_API_KEY"

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const grant = await renza.grants.get("grt_5d2a…");

Response 200

{
  "id": "grt_5d2a…",
  "object": "grant",
  "principal_type": "user",
  "principal": "alice@acme.com",
  "resource_type": "deck",
  "resource": "deck_2a9f…",
  "role": "viewer",
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z"
}

Revoke a grant

DELETE/v1/grants/{id}

Revokes the grant (the principal loses any access it conferred).

Requires an API key (bearer), scoped to the active org. Supports idempotency keys.

Path parameters

idstringrequired

Returns

200The revocation confirmation.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza grants revoke grt_5d2a…

DELETE /v1/grants/{id}

curl https://api.renza.io/v1/grants/grt_5d2a… \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X DELETE

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const grant = await renza.grants.revoke("grt_5d2a…");

Response 200

{
  "object": "grant",
  "deleted": true
}