Identities HTTP API
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 supplies the credentials and entities.
List visible people
Section titled “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
Section titled “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.
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/people" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Create or update a person identity
Section titled “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.
Content-Type: application/json.
Result and recovery
Section titled “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
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'Disable or re-enable a person
Section titled “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. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
disabled (required) |
boolean |
Whether the identity is disabled; disabled identities cannot retain normal access. |
Result and recovery
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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}'List visible logical agents
Section titled “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
Section titled “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.
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/agents" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Disable or re-enable a logical agent
Section titled “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. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
disabled (required) |
boolean |
Whether the identity is disabled; disabled identities cannot retain normal access. |
Result and recovery
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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}'List visible software service identities
Section titled “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
Section titled “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.
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/services" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Create or update a software service identity
Section titled “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.
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
Section titled “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
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'Disable or re-enable a software service
Section titled “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. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
disabled (required) |
boolean |
Whether the identity is disabled; disabled identities cannot retain normal access. |
Result and recovery
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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}'Non-sending current contact observation for an agent
Section titled “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. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
targets (required) |
array of Target | Explicit targets for a private batch or shared chat. These have different audience semantics. maxItems=100. |
Result and recovery
Section titled “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 | 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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}]}'Non-saving, version-checked role-edit preview
Section titled “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.
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
role (required) |
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 | 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
Section titled “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 | 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 | 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 | Optional exact Action descriptor used to evaluate conditional permission, not an executed action. |
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}]}}'Change an Agent or group icon from the bundled pack, or reset its default
Section titled “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.
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
target (required) |
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
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'Update a person’s profile information
Section titled “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. |
Content-Type: application/json.
Result and recovery
Section titled “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
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'Enroll a runtime through a bounded launcher or operator
Section titled “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.
Content-Type: application/json.
Result and recovery
Section titled “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
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'Read an agent’s visible runtime connections
Section titled “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
Section titled “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.
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/agents/${id}/instances" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"List visible directory groups
Section titled “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
Section titled “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.
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/groups" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Create or update a directory group and its members
Section titled “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.
Content-Type: application/json.
Result and recovery
Section titled “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
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"]}'List visible policy roles
Section titled “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
Section titled “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.
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/roles" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Create or version-update a policy role
Section titled “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.
Content-Type: application/json.
Result and recovery
Section titled “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
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}]}'Read visible individual and group role assignments
Section titled “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
Section titled “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.
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/role-bindings" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Add or remove a policy-role assignment
Section titled “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.
Content-Type: application/json.
Result and recovery
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'List credential metadata visible to the operator
Section titled “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
Section titled “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.
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/credentials" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Issue a named API or namespace-restricted enrollment token with an optional expiry and API permission ceiling
Section titled “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.
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
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'Revoke this exact credential, including its rotation overlap
Section titled “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. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
revoke_workers |
boolean |
Also revoke worker credentials enrolled through this credential. default=false. |
Result and recovery
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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 '{}'Rename a token, change expiry or update its permission ceiling using the observed version
Section titled “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. |
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
Section titled “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
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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}'Replace a token secret while preserving its identity, instance and permissions
Section titled “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. |
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
Section titled “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
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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}'Renew the current renewable worker lease, capped by its hard deadline
Section titled “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.
Content-Type: application/json.
object. See the operation-specific result contract.
Result and recovery
Section titled “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
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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 '{}'Link an administrator-attested immutable Slack account to a person
Section titled “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. |
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
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'Link a verified OIDC issuer/subject to a person
Section titled “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. |
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
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'Administrator-attested immutable private Telegram identity
Section titled “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. |
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
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'Unlink the Person Telegram identity under current account-link authority
Section titled “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
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"Administrator-attested immutable Discord application/user identity
Section titled “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. |
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
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"}'Unlink the Person Discord identity
Section titled “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
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
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"