List agent access directory

Outcome

Reads active organization users available for agent ownership or grant decisions. Requires manage_grants or transfer access to this agent and a verifiable Auth directory.

Before you start

• Verify the intended environment, authenticated identity and organization before discovery.
• Discover the published agents:read application permission and inspect the credential-scoped action contract.
• Discover and bind the granted canonical Agent workspace separately from the action input.
• Fixture identifiers and simulated responses confer no live access. Replace identifiers through granted resource discovery.

Discover the target

• topolo whoami --json
• topolo workspaces list topolo-agent --json
• topolo actions get app_topolo_agent.agents.access_directory.list --detail --json
• Read app_topolo_agent.agents.list in this same authorized context and select the returned identifier. Do not derive ids from display names.
• Inspect app_topolo_agent.agents.grants.list in the same credential and resource context before reading it.

Request

GET /api/agents/{id}/access-directory

Input fields

Worked examples

Worked response 1 · HTTP 200

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.

Input · payload.json:

{
  "id": "agent_docs_fixture"
}

CLI:

topolo actions validate app_topolo_agent.agents.access_directory.list --data @payload.json --json
topolo actions plan app_topolo_agent.agents.access_directory.list --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_agent.agents.access_directory.list --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_agent.agents.access_directory.list",
    "input": {
      "id": "agent_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "success": true,
  "users": [
    {
      "id": "usr_reader_fixture",
      "name": "Fixture reader",
      "email": "reader@example.test",
      "role": "member",
      "principalType": null
    }
  ]
}

successful: HTTP 200; seeded local fixture identifiers confer no live access.

Worked response 2 · HTTP 403

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.

Input · payload.json:

{
  "id": "agent_docs_fixture"
}

CLI:

topolo actions validate app_topolo_agent.agents.access_directory.list --data @payload.json --json
topolo actions plan app_topolo_agent.agents.access_directory.list --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_agent.agents.access_directory.list",
    "input": {
      "id": "agent_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 403:

{
  "success": false,
  "error": "Insufficient permissions"
}

permission denied: HTTP 403; SDK code permission_denied; seeded local fixture identifiers confer no live access.

Worked response 3 · HTTP 404

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.

Input · payload.json:

{
  "id": "agent_docs_fixture"
}

CLI:

topolo actions validate app_topolo_agent.agents.access_directory.list --data @payload.json --json
topolo actions plan app_topolo_agent.agents.access_directory.list --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_agent.agents.access_directory.list",
    "input": {
      "id": "agent_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 404:

{
  "success": false,
  "error": "Agent not found"
}

private resource hidden: HTTP 404; SDK code http_error; seeded local fixture identifiers confer no live access.

Verify the result

• Use the returned users[].id for an intended grant recipient. This directory read does not grant that user access or change ownership.

Errors and recovery

• auth_error (HTTP 401): For an unstructured HTTP 401 response, authenticate and verify the intended organization and workspace before retrying.
• permission_denied (HTTP 403): For an unstructured HTTP 403 response, use the published application permission and required resource-level access. Do not retry with broader context.
• http_error (HTTP 404): For an unstructured HTTP 404 response, refresh the corresponding resource listing in the same context. Private resources can be deliberately hidden from this caller.
• agent_directory_unavailable (HTTP 502): The organization directory could not be verified. Retry the read after Auth directory access is restored; do not infer recipients.

Authentication, input validation or resource middleware can refuse a request before these handlers. Preserve the actual refusal and request id.

Recovery boundary

This read does not change service state. Re-discover the target in the same authorized organization and workspace after a missing or hidden-resource refusal; do not guess identifiers or widen context.

Related actions

• List agent access grants: List the active access grants on an agent and who each one is for.

Evidence

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.