Access and permissions

Named agents and their keys, permissions, who may do what.

Start with: access_inspect, agents_create, permissions_set, permissions_list.

15 operations. Discover them from an agent with agentdb_capabilities {"category": "access"}.

#`access.events`

stable

Audit of member, agent and permission-grant changes (owner/admin)

REST: GET /v1/workspaces/{ws}/access-events scope schema:read

Parameter	In	Type	Required	Description
`ws`	path	`string`	yes	string

Example

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/access-events" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`access_inspect`

stable added in 1.0.0-rc.6 read-only

Who you are in this workspace (key, agent or member; role) and what you may do: per object read/write/none, per field access, and owner rules (only records whose user_ref/agent_ref field is you). Hidden objects and fields are not listed and behave as if they did not exist.

MCP tool: access_inspect
REST: GET /v1/workspaces/{ws}/access scope schema:read

Arguments

Argument	Type	Required	Description
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "access_inspect",
  "arguments": {}
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "access_inspect",
    "arguments": {}
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/access" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`agents.keys.create`

stable

Another key for an agent (shown once)

REST: POST /v1/workspaces/{ws}/agents/{agent}/keys scope schema:write

Parameter	In	Type	Required	Description
`ws`	path	`string`	yes	string
`agent`	path	`string`	yes	string

Example

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/agents/<agent>/keys" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`agents_create`

stable added in 1.0.0-rc.6 changes data

Create a named agent with its own API key (shown once) and a role no higher than yours: viewer, editor or admin. Called by an agent, the new agent is its delegate: it inherits your permission rules and stops working when you are revoked. Every action of the new agent is audited as agent:<id>.

MCP tool: agents_create
REST: POST /v1/workspaces/{ws}/agents scope schema:write
CLI: agentdb agents create

Arguments

Argument	Type	Required	Description
`name`	`string`	yes	Name of the agent, shown in audit logs and the app. (min length 1, max length 100)
`role`	`"viewer" \| "editor" \| "admin"`	yes	The agent's role in this workspace.
`description`	`string`		string, up to 1000 characters
`expires_in_hours`	`integer`		integer, 1–8760
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "agents_create",
  "arguments": {
    "name": "Import helper",
    "role": "editor",
    "expires_in_hours": 24
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "agents_create",
    "arguments": {
      "name": "Import helper",
      "role": "editor",
      "expires_in_hours": 24
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/agents" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Import helper","role":"editor","expires_in_hours":24}'

CLI

agentdb agents create [options] <name>

#`agents_list`

stable added in 1.0.0-rc.6 read-only

List named agents of the workspace (owners and admins see all; an agent sees itself and the agents it delegated to): role, status, who granted it, expiry.

MCP tool: agents_list
REST: GET /v1/workspaces/{ws}/agents scope schema:read
CLI: agentdb agents list

Arguments

Argument	Type	Required	Description
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "agents_list",
  "arguments": {}
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "agents_list",
    "arguments": {}
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/agents" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb agents list [options]

#`agents_revoke`

stable added in 1.0.0-rc.6 changes data destructive

Revoke an agent immediately: its keys stop working, and so does every agent it delegated to.

MCP tool: agents_revoke
REST: DELETE /v1/workspaces/{ws}/agents/{agent} scope schema:write
CLI: agentdb agents revoke

Arguments

Argument	Type	Required	Description
`agent_id`	`string`	yes	Agent id (agt_...)
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "agents_revoke",
  "arguments": {
    "agent_id": "agt_example"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "agents_revoke",
    "arguments": {
      "agent_id": "agt_example"
    }
  }
}

REST

curl -s -X DELETE "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/agents/agt_example" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb agents revoke [options] <agent_id>

#`me`

stable

The calling key: type, workspace, scopes

REST: GET /v1/me

Example

REST

curl -s "https://app.agentdb.link/v1/me" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`me.revoke`

stable

Revoke the calling key

REST: POST /v1/me/revoke

Example

REST

curl -s -X POST "https://app.agentdb.link/v1/me/revoke" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`members.invite`

stable

Invite a person by email with a role (viewer, editor, admin)

REST: POST /v1/workspaces/{ws}/members scope schema:write

Parameter	In	Type	Required	Description
`ws`	path	`string`	yes	string

JSON body: the arguments in the table above, as an object.

Example

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/members" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`members.list`

stable

Owner and members with roles (owner/admin)

REST: GET /v1/workspaces/{ws}/members scope schema:read

Parameter	In	Type	Required	Description
`ws`	path	`string`	yes	string

Example

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/members" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`members.remove`

stable

Remove a member or withdraw an invitation

REST: DELETE /v1/workspaces/{ws}/members/{member} scope schema:write

Parameter	In	Type	Required	Description
`ws`	path	`string`	yes	string
`member`	path	`string`	yes	string

Example

REST

curl -s -X DELETE "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/members/<member>" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`members.update`

stable

Change a member's role

REST: PATCH /v1/workspaces/{ws}/members/{member} scope schema:write

Parameter	In	Type	Required	Description
`ws`	path	`string`	yes	string
`member`	path	`string`	yes	string

JSON body: the arguments in the table above, as an object.

Example

REST

curl -s -X PATCH "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/members/<member>" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`permissions_list`

stable added in 1.0.0-rc.6 read-only

MCP tool: permissions_list
REST: GET /v1/workspaces/{ws}/permissions scope schema:read
CLI: agentdb permissions list

Arguments

Argument	Type	Required	Description
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "permissions_list",
  "arguments": {}
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "permissions_list",
    "arguments": {}
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/permissions" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb permissions list [options]

#`permissions_remove`

stable added in 1.0.0-rc.6 changes data destructive

Remove one permission rule; the subject falls back to its role's rights.

MCP tool: permissions_remove
REST: DELETE /v1/workspaces/{ws}/permissions/{rule} scope schema:write
CLI: agentdb permissions remove

Arguments

Argument	Type	Required	Description
`rule_id`	`string`	yes	Rule id (prm_...) from permissions_list
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

rule_id comes from permissions_list.

MCP

{
  "tool": "permissions_remove",
  "arguments": {
    "rule_id": "prm_example"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "permissions_remove",
    "arguments": {
      "rule_id": "prm_example"
    }
  }
}

REST

curl -s -X DELETE "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/permissions/prm_example" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

CLI

agentdb permissions remove [options] <rule_id>

#`permissions_set`

stable added in 1.0.0-rc.6 changes data

Create or replace one permission rule (owners and admins without rules). Example: hide salary from editors {subject: 'role:editor', object: 'employee', field: 'salary', access: 'none'}; let an agent see only its own tasks {subject: 'agent:agt_…', object: 'task', access: 'write', owner_field: 'assignee'} (owner_field must be a user_ref or agent_ref field). Hidden fields disappear from reads, filters, aggregates, the change feed and exports.

MCP tool: permissions_set
REST: POST /v1/workspaces/{ws}/permissions scope schema:write
CLI: agentdb permissions set

Arguments

Argument	Type	Required	Description
`subject`	`string`	yes	Who the rule is for: role:viewer, role:editor, user:acc_... or agent:agt_....
`object`	`"*" \| string`	yes	Object type name, or * for every object.
`field`	`string`		string
`access`	`"none" \| "read" \| "write"`	yes	What the subject may do with the object.
`owner_field`	`string`		string
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "permissions_set",
  "arguments": {
    "subject": "role:viewer",
    "object": "deal",
    "field": "amount",
    "access": "none"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "permissions_set",
    "arguments": {
      "subject": "role:viewer",
      "object": "deal",
      "field": "amount",
      "access": "none"
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/permissions" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject":"role:viewer","object":"deal","field":"amount","access":"none"}'

CLI

agentdb permissions set [options] <subject> <object> [field]

Access and permissions

#access.events

Example

#access_inspect

Arguments

Example

#agents.keys.create

Example

#agents_create

Arguments

Example

#agents_list

Arguments

Example

#agents_revoke

Arguments

Example

#me

Example

#me.revoke

Example

#members.invite

Example

#members.list

Example

#members.remove

Example

#members.update

Example

#permissions_list

Arguments

Example

#permissions_remove

Arguments

Example

#permissions_set

Arguments

Example

#`access.events`

#`access_inspect`

#`agents.keys.create`

#`agents_create`

#`agents_list`

#`agents_revoke`

#`me`

#`me.revoke`

#`members.invite`

#`members.list`

#`members.remove`

#`members.update`

#`permissions_list`

#`permissions_remove`

#`permissions_set`