# Identities HTTP API

Inputs, results, permissions and errors for the identities endpoints.

Use the server URL of your own deployment. Worker examples require a currently valid bearer token; provider callbacks use native signatures. `REPLACE_WITH_RETURNED_ID` values refer to IDs obtained through setup or prior operations. [Headless setup](https://beepgrid.com/docs/start/headless.md) supplies the credentials and entities.

<a id="get-api-v1-people"></a>

## List visible people

`GET /api/v1/people`

List visible people.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Result and recovery

Array of Person records. Use query for complete pagination.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. Array result.

[Person](https://beepgrid.com/docs/reference/models/#person)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/people" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-people"></a>

## Create or update a person identity

`POST /api/v1/people`

Create or update a person identity.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Input

Content-Type: `application/json`.

[PersonInput](https://beepgrid.com/docs/reference/models/#personinput)

### Result and recovery

Person with its stable id. Email metadata alone does not verify a provider account.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. [Person](https://beepgrid.com/docs/reference/models/#person)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/people" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Builder 7"}'
```

<a id="post-api-v1-people-id-status"></a>

## Disable or re-enable a person

`POST /api/v1/people/{id}/status`

Disable or re-enable a person.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `disabled` (required) | `boolean` | Whether the identity is disabled; disabled identities cannot retain normal access. |

### Result and recovery

`{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `ok` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/people/${id}/status" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"disabled":false}'
```

<a id="get-api-v1-agents"></a>

## List visible logical agents

`GET /api/v1/agents`

List visible logical agents.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Result and recovery

Array of Agent records, separate from runtime instances.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. Array result.

[Agent](https://beepgrid.com/docs/reference/models/#agent)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/agents" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-agents-id-status"></a>

## Disable or re-enable a logical agent

`POST /api/v1/agents/{id}/status`

Disable or re-enable a logical agent.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `disabled` (required) | `boolean` | Whether the identity is disabled; disabled identities cannot retain normal access. |

### Result and recovery

`{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `ok` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/agents/${id}/status" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"disabled":false}'
```

<a id="get-api-v1-services"></a>

## List visible software service identities

`GET /api/v1/services`

List visible software service identities.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Result and recovery

Array of Service records.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. Array result.

[Service](https://beepgrid.com/docs/reference/models/#service)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/services" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-services"></a>

## Create or update a software service identity

`POST /api/v1/services`

Create or update a software service identity.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `external_id` (required) | `string` | Your stable identifier for this person, agent or service within the workspace. |
| `name` (required) | `string` | Human-readable name. It is not necessarily unique. |

### Result and recovery

Service with a stable id for credentials and contact policy.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. [Service](https://beepgrid.com/docs/reference/models/#service)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/services" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"external_id":"REPLACE_WITH_RETURNED_ID","name":"Builder 7"}'
```

<a id="post-api-v1-services-id-status"></a>

## Disable or re-enable a software service

`POST /api/v1/services/{id}/status`

Disable or re-enable a software service.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `disabled` (required) | `boolean` | Whether the identity is disabled; disabled identities cannot retain normal access. |

### Result and recovery

`{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `ok` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/services/${id}/status" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"disabled":false}'
```

<a id="post-api-v1-agents-id-contacts"></a>

## Non-sending current contact observation for an agent

`POST /api/v1/agents/{id}/contacts`

Non-sending current contact observation for an agent. Requires subject access inspection. Returns only caller-visible contacts that the agent can view and contact. Channel kinds/modes are shown only where the caller can inspect the recipient destination. No addresses, installation IDs, credentials or send authority are returned.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `targets` (required) | array of [Target](https://beepgrid.com/docs/reference/models/#target) | Explicit targets for a private batch or shared chat. These have different audience semantics. maxItems=100. |

### Result and recovery

AgentContacts: contacts with target, name, message/ask capability and route projections, plus observed_at.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `contacts` | array of `object` | Authorized contact observations, including available operations and delivery route evidence. |
| `observed_at` | `string` | Timestamp of this capability snapshot. |

**`contacts` fields**

Array result.

| Field | Type | Usage |
| --- | --- | --- |
| `contacts[].target` | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `contacts[].name` | `string` | Human-readable name. It is not necessarily unique. |
| `contacts[].message` | `boolean` | Safe human-readable API error message. |
| `contacts[].ask` | `boolean` | Whether the subject may initiate a requested reply to this contact. |
| `contacts[].routes` | array of `object` | Visible route projections; no destination secrets or installation credentials. |

**`contacts[].routes` fields**

Array result.

| Field | Type | Usage |
| --- | --- | --- |
| `contacts[].routes[].kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `contacts[].routes[].mode` | `string` | primary, copy or fallback routing mode. |
| `contacts[].routes[].enabled` | `boolean` | Whether this configured connection is enabled. |
| `contacts[].routes[].permitted` | `boolean` | Whether current contact and route policy permits this route. |
| `contacts[].routes[].reason` | `string` | Human-readable explanation of the current policy or routing result. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/agents/${id}/contacts" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"targets":[{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"}]}'
```

<a id="post-api-v1-roles-preview"></a>

## Non-saving, version-checked role-edit preview

`POST /api/v1/roles/preview`

Non-saving, version-checked role-edit preview. Same rule ceiling and assignment boundaries as SaveRole; reports exact affected assignments and before/after role-grant checks for authorized subjects. Administrator credential power and new assignments are not simulated. Other assigned roles remain effective.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `role` (required) | [Role](https://beepgrid.com/docs/reference/models/#role) | Policy role object to preview or inspect; separate from an agent_role directory group. |
| `checks` | array of `object` | Concrete subject/action/target checks for a non-saving policy-role preview. |

**`checks` fields**

Array result.

| Field | Type | Usage |
| --- | --- | --- |
| `checks[].subject_id` (required) | `string` | Identity or directory group receiving a policy-role assignment. |
| `checks[].action` (required) | `string` | Optional exact bound-action descriptor for the advanced execution contract. |
| `checks[].target` (required) | `object` | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `checks[].connection_id` | `string` | Configured channel connection ID. |
| `checks[].action_name` | `string` | Optional action-name constraint; not required for ordinary approval communication. |
| `checks[].descriptor` | [Action](https://beepgrid.com/docs/reference/models/#action) | Optional exact Action descriptor used to evaluate conditional permission, not an executed action. |

**`checks[].target` fields**

| Field | Type | Usage |
| --- | --- | --- |
| `checks[].target.kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `checks[].target.id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |

### Result and recovery

`can_save`, current `version`, `affected_assignments`, before/after `checks`, `basis` and `saves=false`. This simulates existing assignments without saving or granting new ones.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `can_save` | `boolean` | Whether current authority permits this proposal. |
| `version` | `integer` | Current role revision. |
| `affected_assignments` | array of [Binding](https://beepgrid.com/docs/reference/models/#binding) | Existing bindings affected by this role. |
| `checks` | array of `object` | Bounded permission comparisons. |
| `basis` | `string` | effective_role_grants; administrator bypass is excluded from simulation. |
| `saves` | `boolean` | Always false. |

**`checks` fields**

Array result.

| Field | Type | Usage |
| --- | --- | --- |
| `checks[].check` | `object` | The concrete subject, action, target and optional conditions being simulated. |
| `checks[].before` | `boolean` | Current effective permission. |
| `checks[].after` | `boolean` | Effective permission under the proposed role. |

**`checks[].check` fields**

| Field | Type | Usage |
| --- | --- | --- |
| `checks[].check.subject_id` | `string` | Principal whose effective grants are simulated. |
| `checks[].check.action` | `string` | Permission action. |
| `checks[].check.target` | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `checks[].check.connection_id` | `string` | Optional route condition. |
| `checks[].check.action_name` | `string` | Optional business action name. |
| `checks[].check.descriptor` | [Action](https://beepgrid.com/docs/reference/models/#action) | Optional exact Action descriptor used to evaluate conditional permission, not an executed action. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/roles/preview" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"role":{"name":"Builder 7","rules":[{"action":"view","target_kind":"REPLACE_WITH_TARGET_KIND","target_id":"REPLACE_WITH_RETURNED_ID"}]}}'
```

<a id="post-api-v1-appearance"></a>

## Change an Agent or group icon from the bundled pack, or reset its default

`POST /api/v1/appearance`

Change an Agent or group icon from the bundled pack, or reset its default.

**Authorization:** A current manager of the target Agent or group.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `target` (required) | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `icon` (required) | `string` | mark-0 through mark-11 for an Agent; role-0 through role-11 for a group. Empty resets to its default. |
| `version` | `integer` | Current group revision. Required for an existing group. |

### Result and recovery

Target, selected icon and current group version. Appearance changes do not alter membership or permissions.

Invalid icons are rejected. A stale group revision conflicts. Other workspaces and unmanaged identities remain inaccessible.

Response media type: `application/json`. `object`. See the operation-specific result contract.


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/appearance" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"target":{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"},"icon":"REPLACE_WITH_ICON"}'
```

<a id="post-api-v1-people-id-profile"></a>

## Update a person's profile information

`POST /api/v1/people/{id}/profile`

Update a person's profile information.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

[PersonInput](https://beepgrid.com/docs/reference/models/#personinput)

### Result and recovery

Updated Person. This does not change their policy-role bindings.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. [Person](https://beepgrid.com/docs/reference/models/#person)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/people/${id}/profile" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Builder 7"}'
```

<a id="post-api-v1-sessions"></a>

## Enroll a runtime through a bounded launcher or operator

`POST /api/v1/sessions`

Enroll a runtime through a bounded launcher or operator.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Input

Content-Type: `application/json`.

[Enrollment](https://beepgrid.com/docs/reference/models/#enrollment)

### Result and recovery

Session containing a new worker token, logical Agent, exact instance_id and expires_at. The token is secret.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. [Session](https://beepgrid.com/docs/reference/models/#session)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/sessions" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"agent":"REPLACE_WITH_AGENT","name":"Builder 7"}'
```

<a id="get-api-v1-agents-id-instances"></a>

## Read an agent's visible runtime connections

`GET /api/v1/agents/{id}/instances`

Read an agent's visible runtime connections.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Result and recovery

Array of Instance presence/progress observations.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. Array result.

[Instance](https://beepgrid.com/docs/reference/models/#instance)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/agents/${id}/instances" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="get-api-v1-groups"></a>

## List visible directory groups

`GET /api/v1/groups`

List visible directory groups.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Result and recovery

Group array. purpose distinguishes teams, agent roles and contact groups.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. Array result.

[Group](https://beepgrid.com/docs/reference/models/#group)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/groups" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-groups"></a>

## Create or update a directory group and its members

`POST /api/v1/groups`

Create or update a directory group and its members.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Input

Content-Type: `application/json`.

[Group](https://beepgrid.com/docs/reference/models/#group)

### Result and recovery

Group with id and version. This does not create a shared chat.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. [Group](https://beepgrid.com/docs/reference/models/#group)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/groups" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Builder 7","members":["value"]}'
```

<a id="get-api-v1-roles"></a>

## List visible policy roles

`GET /api/v1/roles`

List visible policy roles.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Result and recovery

Role array. These are permission rule sets, separate from agent roles.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. Array result.

[Role](https://beepgrid.com/docs/reference/models/#role)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/roles" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-roles"></a>

## Create or version-update a policy role

`POST /api/v1/roles`

Create or version-update a policy role.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Input

Content-Type: `application/json`.

[Role](https://beepgrid.com/docs/reference/models/#role)

### Result and recovery

Saved Role. Delegated managers cannot grant authority beyond their own ceiling.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. [Role](https://beepgrid.com/docs/reference/models/#role)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/roles" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Builder 7","rules":[{"action":"view","target_kind":"REPLACE_WITH_TARGET_KIND","target_id":"REPLACE_WITH_RETURNED_ID"}]}'
```

<a id="get-api-v1-role-bindings"></a>

## Read visible individual and group role assignments

`GET /api/v1/role-bindings`

Read visible individual and group role assignments.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Result and recovery

Binding array.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. Array result.

[Binding](https://beepgrid.com/docs/reference/models/#binding)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/role-bindings" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-role-bindings"></a>

## Add or remove a policy-role assignment

`POST /api/v1/role-bindings`

Add or remove a policy-role assignment.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Input

Content-Type: `application/json`.

[Binding](https://beepgrid.com/docs/reference/models/#binding)

### Result and recovery

`{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `ok` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/role-bindings" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"role_id":"REPLACE_WITH_RETURNED_ID","subject_kind":"principal","subject_id":"REPLACE_WITH_RETURNED_ID"}'
```

<a id="get-api-v1-credentials"></a>

## List credential metadata visible to the operator

`GET /api/v1/credentials`

List credential metadata visible to the operator.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Result and recovery

Metadata array with expiry/revocation state; no recoverable plaintext tokens.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. Array result.

[Credential](https://beepgrid.com/docs/reference/models/#credential)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/credentials" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-credentials"></a>

## Issue a named API or namespace-restricted enrollment token with an optional expiry and API permission ceiling

`POST /api/v1/credentials`

Issue a named API or namespace-restricted enrollment token with an optional expiry and API permission ceiling. Defaults to 30 days.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `principal_id` (required) | `string` | Person, agent or service identity ID. This is an API term, not a separate product entity. |
| `kind` (required) | `api \| enrollment` | Resource or operation kind. Use one of the listed values, not a display label. |
| `prefix` | `string` | Permitted enrollment namespace prefix for a bounded launcher. |
| `name` | `string` | Human-readable name. It is not necessarily unique. |
| `never_expires` | `boolean` | Explicitly request a non-expiring credential. Cannot be combined with an expiry or renewable worker lease. default=false. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. format="date-time". |
| `permissions` | array of `read \| message \| request \| respond \| execute \| manage` | Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply. |

### Result and recovery

Token secret once with id, kind and expires_at. Metadata listing never recovers plaintext.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `id` | `string` | New credential ID. |
| `token` | `string` | One-time secret; save in a protected credential file. |
| `kind` | `string` | Issued credential kind: api or enrollment. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/credentials" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"principal_id":"REPLACE_WITH_RETURNED_ID","kind":"api"}'
```

<a id="post-api-v1-credentials-id-revoke"></a>

## Revoke this exact credential, including its rotation overlap

`POST /api/v1/credentials/{id}/revoke`

Revoke this exact credential, including its rotation overlap. An enrollment token may explicitly revoke_workers to stop connections it issued after lineage tracking was introduced.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `revoke_workers` | `boolean` | Also revoke worker credentials enrolled through this credential. default=false. |

### Result and recovery

`{revoked: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `revoked` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/credentials/${id}/revoke" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
```

<a id="post-api-v1-credentials-id-edit"></a>

## Rename a token, change expiry or update its permission ceiling using the observed version

`POST /api/v1/credentials/{id}/edit`

Rename a token, change expiry or update its permission ceiling using the observed version.

**Authorization:** Authorized credential manager, or the current worker for self-renewal. Token limits never grant identity permissions.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `version` (required) | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `name` | `string` | Human-readable name. It is not necessarily unique. |
| `never_expires` | `boolean` | Explicitly request a non-expiring credential. Cannot be combined with an expiry or renewable worker lease. |
| `expires_at` | `string` | Expiry timestamp. Ordinary communication has no implicit deadline (represented as 9999-01-01T00:00:00Z). Bound action approvals default to seven days; explicit expiry must be within ninety days. Local wait timeout never changes it. format="date-time". |
| `permissions` | array of `string` | Optional credential-specific restriction to read, message, request, respond, execute or manage. Underlying identity permissions still apply. |
| `clear_permissions` | `boolean` | Remove the credential-specific permission restriction. This does not grant permissions absent from the underlying identity. |

### Result and recovery

Current metadata with the next version. Never returns the secret.

Stale versions conflict. Expired or revoked tokens cannot renew or rotate. Restricted tokens cannot mint or broaden credentials.

Response media type: `application/json`. [Credential](https://beepgrid.com/docs/reference/models/#credential)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/credentials/${id}/edit" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"version":1}'
```

<a id="post-api-v1-credentials-id-rotate"></a>

## Replace a token secret while preserving its identity, instance and permissions

`POST /api/v1/credentials/{id}/rotate`

Replace a token secret while preserving its identity, instance and permissions. Choose a zero to 86400 second overlap.

**Authorization:** Authorized credential manager, or the current worker for self-renewal. Token limits never grant identity permissions.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `version` (required) | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `overlap_seconds` | `integer` | How long the previous token remains usable after rotation, from zero to 86400 seconds. Defaults to 3600. minimum=0, maximum=86400, default=3600. |

### Result and recovery

New token secret once, plus metadata including previous_until. No automatic retry after an uncertain outcome.

Stale versions conflict. Expired or revoked tokens cannot renew or rotate. Restricted tokens cannot mint or broaden credentials.

Response media type: `application/json`. [CredentialReplacement](https://beepgrid.com/docs/reference/models/#credentialreplacement)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/credentials/${id}/rotate" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"version":1}'
```

<a id="post-api-v1-credentials-self-renew"></a>

## Renew the current renewable worker lease, capped by its hard deadline

`POST /api/v1/credentials/self/renew`

Renew the current renewable worker lease, capped by its hard deadline. Active traffic renews near expiry automatically.

**Authorization:** Authorized credential manager, or the current worker for self-renewal. Token limits never grant identity permissions.


### Input

Content-Type: `application/json`.

`object`. See the operation-specific result contract.

### Result and recovery

Current credential metadata. No new instance or secret is created.

Stale versions conflict. Expired or revoked tokens cannot renew or rotate. Restricted tokens cannot mint or broaden credentials.

Response media type: `application/json`. [Credential](https://beepgrid.com/docs/reference/models/#credential)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/credentials/self/renew" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
```

<a id="post-api-v1-people-id-slack-account"></a>

## Link an administrator-attested immutable Slack account to a person

`POST /api/v1/people/{id}/slack-account`

Link an administrator-attested immutable Slack account to a person.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `team_id` (required) | `string` | Immutable Slack workspace/team ID for the linked account. |
| `user_id` (required) | `string` | Immutable provider user ID; not the display name or email. |

### Result and recovery

`{linked: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `linked` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/people/${id}/slack-account" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"team_id":"REPLACE_WITH_RETURNED_ID","user_id":"REPLACE_WITH_RETURNED_ID"}'
```

<a id="post-api-v1-people-id-oidc-account"></a>

## Link a verified OIDC issuer/subject to a person

`POST /api/v1/people/{id}/oidc-account`

Link a verified OIDC issuer/subject to a person.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `issuer` (required) | `string` | Exact OIDC issuer URL used with the immutable subject; email matching alone is not identity linking. |
| `subject` (required) | `string` | Authorized subject projection of the access inspection. |

### Result and recovery

`{linked: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `linked` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/people/${id}/oidc-account" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"issuer":"REPLACE_WITH_ISSUER","subject":"REPLACE_WITH_SUBJECT"}'
```

<a id="post-api-v1-people-id-telegram-account"></a>

## Administrator-attested immutable private Telegram identity

`POST /api/v1/people/{id}/telegram-account`

Administrator-attested immutable private Telegram identity. Grants no contact or decision authority.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `bot_id` (required) | `string` | Provider-native bot identity for the configured application. |
| `user_id` (required) | `string` | Immutable provider user ID; not the display name or email. |

### Result and recovery

`{linked: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `linked` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/people/${id}/telegram-account" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"bot_id":"REPLACE_WITH_RETURNED_ID","user_id":"REPLACE_WITH_RETURNED_ID"}'
```

<a id="post-api-v1-people-id-telegram-account-remove"></a>

## Unlink the Person Telegram identity under current account-link authority

`POST /api/v1/people/{id}/telegram-account/remove`

Unlink the Person Telegram identity under current account-link authority. Old destinations and callbacks lose authority.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Result and recovery

`{removed: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `removed` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/people/${id}/telegram-account/remove" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json"
```

<a id="post-api-v1-people-id-discord-account"></a>

## Administrator-attested immutable Discord application/user identity

`POST /api/v1/people/{id}/discord-account`

Administrator-attested immutable Discord application/user identity. Grants no contact or decision authority.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `application_id` (required) | `string` | Immutable Discord application ID for the configured connection. |
| `user_id` (required) | `string` | Immutable provider user ID; not the display name or email. |

### Result and recovery

`{linked: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `linked` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/people/${id}/discord-account" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"application_id":"REPLACE_WITH_RETURNED_ID","user_id":"REPLACE_WITH_RETURNED_ID"}'
```

<a id="post-api-v1-people-id-discord-account-remove"></a>

## Unlink the Person Discord identity

`POST /api/v1/people/{id}/discord-account/remove`

Unlink the Person Discord identity. Queued sends and callbacks lose authority.

**Authorization:** Authenticated identity; mutations require management authority over the relevant resource. Enrollment requires a bounded launcher or operator.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Result and recovery

`{removed: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Unknown/hidden identity is 404 or denied. Stale version conflicts. Delegated managers cannot create broader authority than they possess; revoked credentials cannot be used.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `removed` | `boolean` | True after the operation succeeds. |


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/people/${id}/discord-account/remove" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json"
```