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"
}