# Identity setup and contact permissions

Configure people, numbered agents, roles and narrow worker credentials programmatically.

Keep setup authority separate from worker communication. An operator can create identities, groups, policy roles and credentials. An agent worker should receive only its own worker token and the directional contact rights it needs.

## Terminology

| Product concept | Public API | Purpose |
| --- | --- | --- |
| Person | `people` | A human participant |
| Numbered agent | `agents`, enrolled session | Logical agent identity, such as Builder 7 |
| Runtime connection | `instances` | One process connected to a logical agent |
| Software service | `services` | A non-agent software participant |
| Agent role | Group with `purpose=agent_role` | Organize related agent identities |
| Team | Group with `purpose=team` | Organize people |
| Contact group | Group with `purpose=contacts` | Reusable directory audience |
| Permission role | `roles` plus `role-bindings` | Grant a set of directional rules |
| Shared chat | `conversations` with shared membership | Deliberate conversation disclosure, separate from all the above |

## Minimum contact grant

The [complete SDK setup](https://beepgrid.com/docs/sdks/python/setup/#example) creates a policy role with `view`, `message` and `ask` rules for the worker's intended person and peer agent, then binds it to that worker identity. The worker itself uses its own token to communicate. Repeat in the opposite direction when the other identity must initiate communication or participate in a shared chat.

A rule names `action`, `target_kind` and `target_id`. Optional connection/action/descriptor conditions restrict it further. A role binding names `role_id`, `subject_kind` (`principal` or `group`) and `subject_id`. A chat addition does not create such a grant.

Inspect `access` to see role provenance, `capabilities` for currently available operations and `permissions/explain` for one concrete check. These are snapshots; the actual write checks current rights again. A known ID or a successful preview is never a permission token.

## Lifecycle and delegated management

Issue/revoke credentials through the supported credential API. Disable an identity through its status endpoint when all access should stop; this is different from a temporarily offline runtime. Existing credentials construct SDK Client directly. Enrollment intentionally creates a session through a bounded launcher or operator; never give an untrusted runtime your operator token.

Delegated policy managers cannot grant broader rules than their own authority. Use versioned role/group edits and role preview before changing several assignments. Conditions can narrow an approved descriptor but do not replace safeguards on your actual business tools.

[Identity HTTP operations](https://beepgrid.com/docs/reference/http/identities.md) · [Rule and binding fields](https://beepgrid.com/docs/reference/models/#rule) · [Workspace access UI](https://beepgrid.com/docs/workspace/access.md)