A grant is the smallest authorization unit in Flocks. It’s a typed JSON envelope, signed by the gateway, that says:
  • What: which driver, which model, with which arguments.
  • Where: the assigned roost.
  • How long: TTL.
  • Which tools: capability-scoped allowlist for /v1/tool calls.
{
  "version": 1,
  "gateway_id": "ed25519:…",
  "roost_id":   "ed25519:…",
  "driver":     "codex",
  "model":      "gpt-5.5",
  "expires_at": "2026-04-26T01:00:00Z",
  "tools":      ["flocks.builtin.shell", "flocks.builtin.git"],
  "signature":  "…"
}

​
Why it matters

  • Denied by default. Without a grant, no agent runs. Without a matching tool capability, no tool fires.
  • Verifiable. Every line of the audit log can be replayed against the gateway’s public key.
  • No amplification. A grant cannot be re-delegated more powerfully than its parent.