---
title: "Issue a context grant to an agent"
method: POST
path: "/context/grants"
tags: ["Setup · Context grants"]
---

# Issue a context grant to an agent

`POST /context/grants`

## Request

- Base URL: `https://api.ziggsai.com`
- URL: `https://api.ziggsai.com/context/grants`
- Auth: HTTP bearer

## Request body

- IssueContextGrantDto
  - `holderId` string, required: Who receives the grant: a person, an organization, or an agent. An organization holder covers every one of its members with one grant.
  - `holderKind` 'user' | 'org' | 'agent', required: What kind of holder `holderId` is. Always state it; ids carry no type.
  - `kind` 'read' | 'write' | 'admit': What the holder may do: `read` to see it, `write` to take part, `admit` to bring others in as well. Defaults to `write`. An agent holding a whole workspace (`scope.kind: org`) only ever gets `read`: it takes part where it is a party, so anything else is refused.
  - `scope` ContextGrantScopeDto, required
    - `kind` 'chat' | 'agreement' | 'org' | 'artifact' | 'task' | 'person', required: What the grant points at. `artifact` is the narrowest: one specific artifact, shared without sharing any chat or agreement it sits in. `task` is a branch of a work graph: the named task and everything under it, now and in future. Holding one is what it means to be in a job: a holder with `write` may create work inside the branch, a holder with only `read` is watching it. `person` names one person by id and is held only at `list`: it lets the holder see which rooms that person is in, never what is in them.
    - `id` string, required: chatId, agreementId, orgId, artifactId, taskId, or a person id
  - `temporal` 'from-now' | 'from-start'
  - `expiresAt` object: ISO-8601 expiry; omit for default TTL

## Response `201`

Created

- GrantIssueResponseSchema
  - `grant` GrantViewSchema, required
    - `grantId` string, required
    - `issuerId` string, required: Principal that issued the grant (root owner or delegator).
    - `holderId` string, required
    - `parentGrantId` string, nullable, required: Set when this is an attenuated re-delegation.
    - `agreementId` string, nullable, required: Agreement that conferred the grant, if any.
    - `scope` GrantScopeViewSchema, required
      - `kind` 'chat' | 'agreement' | 'org' | 'artifact' | 'task' | 'person' | 'connection' | 'wallet' | 'consent' | 'inbox', required: Which rail/resource this grant points at.
      - `id` string, required: Id of the scoped resource.
      - `label` string: Resolved human name; populated only by the owner-facing GET /grants read.
    - `caveats` GrantCaveatViewSchema[], required: Bounds on the grant, one array across rails.
      - `type` string, required: Caveat name (allowed_actions, max_amount, temporal, …).
      - `value` object, required: Shape depends on type. max_amount and daily_budget are a number of hundredths of a point.
    - `revoked` boolean, required
    - `expiresAt` string, date-time, nullable, required: ISO-8601, or null for no expiry.
    - `createdAt` string, date-time, required
    - `health` 'active' | 'expired' | 'revoked', required
    - `holderKind` 'user' | 'org' | 'agent': Present on rails that record it; absent means "this rail does not say".
    - `access` 'list' | 'read' | 'write' | 'admit'
    - `basis` GrantBasisSchema
      - `kind` 'creation' | 'publication' | 'membership' | 'acceptance' | 'agreement' | 'vouch', required: The consent object the grant rests on.
      - `id` string, nullable, required: Id of the consent object, if any.

---

[API](https://skmtc.dev/ziggsai/apis/ziggs-developer-api.md) · [All operations](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ziggsai/apis/ziggs-developer-api/revisions/eda79030e072?raw)