List user permission overrides

List stored explicit allow/deny rows for one user, including duplicate and expired records; effective access needs separate evaluation.

Outcome

List stored explicit allow/deny rows for one user, including duplicate and expired records; effective access needs separate evaluation.

These examples prove local handler behavior with real isolated SQL and explicitly simulated identity/permission dependencies.

Before you start

Verify the intended authenticated identity and the current credential-scoped action before preparing input. Self and managed-user security operations have different authority; an override id does not authorize a different user or organization.
Use authorized identity and user/session discovery. Recovery security data and session/device identifiers must remain inside the caller-approved workflow.

Discover the target

topolo whoami --json
topolo apps --json
topolo actions get app_topolo_auth.user_permission_overrides.list --detail --json

Discover the exact user and organization membership, application and service_permissions.list entries. Read user_permission_overrides.list with exact org/app filters; use its row id, user and organization together. Read user_permissions.get separately for effective access.

Input fields

Field	Required	Meaning
`userId`	Yes	Existing Topolo identity from authorized user discovery. Read allows self or a permitted manager. Writes require an organization administrator role and authority over the actual override organization, not merely a known row id.
`orgId`	No	Read filter or required create organization. The target identity must belong to it under the handler membership resolution. An omitted read filter queries this user across organizations; it is not a pagination cursor. Delete obtains organization from the exact stored user/override row and checks that organization authority.
`appId`	No	Canonical application from credential-scoped discovery. Select the exact application owning the declared permission. An omitted read filter queries stored overrides across applications; override creation does not assign application access or a seat.

Effects

Reads explicit stored override rows, including duplicates and expired records; no effective permission evaluation is implied.

Interpret the response

Raw target successes have success/message/data/timestamp; creation is HTTP 201 and read/delete are 200. CLI/MCP may wrap or project the response. Stored fields are snake_case with epoch seconds; the envelope timestamp is ISO text. Fixtures prove local canonical SQL/handler behavior with simulated token identity, target memberships and permission catalog partitions, not live effective permission enforcement.

data.userId/orgId/appId echo the target and supplied filters; omitted filters are null. overrides is the stored-row set, ordered by created_at descending, with no continuation or limit. It includes duplicates, conflicting effects and expired rows; it is not the effective permission result. Self can read its stored rows, while management of others checks the selected organization context or target identity.

An explicit organization must resolve as the target active organization or a recorded membership not marked deleted/inactive. This resolver does not itself prove active app assignment, current app execution permission or seat entitlement. An omitted org filter can return this user rows across organizations even when management was checked against its active projection, so keep the data within the authorized security workflow and use exact filters for a specific organization decision.

Worked examples

These are complete raw target-handler responses, not CLI/gateway envelopes or live authorization proof. Replace synthetic identifiers using authorized discovery. Save only the reviewed input as payload.json; inspect validation and plan before executing. --confirm assumes the intended operation is approved. Storage read-back and actual sign-in outcomes require separate verification. Explicit rows do not assign app access or seats, and duplicate/conflicting overrides can remain. Removing a deny can increase access. Cookies and Bearer tokens must identify the intended principal consistently.

Exact organization/application read starts with no explicit overrides

Input · payload.json:

{
  "userId": "usr_managed",
  "orgId": "org_example",
  "appId": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.user_permission_overrides.list --data @payload.json --json
topolo actions plan app_topolo_auth.user_permission_overrides.list --data @payload.json --json
topolo actions call app_topolo_auth.user_permission_overrides.list --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.user_permission_overrides.list",
    "input": {
      "userId": "usr_managed",
      "orgId": "org_example",
      "appId": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "User permission overrides fetched",
  "data": {
    "userId": "usr_managed",
    "orgId": "org_example",
    "appId": "app_topolo_campaigns",
    "overrides": []
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Listing includes duplicate and expired rows; it is not effective permission evaluation

Input · payload.json:

{
  "userId": "usr_managed",
  "orgId": "org_example",
  "appId": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.user_permission_overrides.list --data @payload.json --json
topolo actions plan app_topolo_auth.user_permission_overrides.list --data @payload.json --json
topolo actions call app_topolo_auth.user_permission_overrides.list --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.user_permission_overrides.list",
    "input": {
      "userId": "usr_managed",
      "orgId": "org_example",
      "appId": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "User permission overrides fetched",
  "data": {
    "userId": "usr_managed",
    "orgId": "org_example",
    "appId": "app_topolo_campaigns",
    "overrides": [
      {
        "id": "upo_FfLusJrOwlvd",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.read",
        "effect": "allow",
        "expires_at": null,
        "created_at": 1790899200
      },
      {
        "id": "upo_E-G6cLsM_852",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.read",
        "effect": "allow",
        "expires_at": null,
        "created_at": 1790899200
      },
      {
        "id": "upo_JnwqYI7Kow_Z",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.read",
        "effect": "deny",
        "expires_at": null,
        "created_at": 1790899200
      },
      {
        "id": "upo_7xT5fqF91l9B",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.write",
        "effect": "allow",
        "expires_at": 1790899199,
        "created_at": 1790899200
      },
      {
        "id": "upo_nNFZ7808mFji",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.write",
        "effect": "allow",
        "expires_at": 0,
        "created_at": 1790899200
      }
    ]
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Self can read its stored overrides without organization/application filters

Input · payload.json:

{
  "userId": "usr_managed"
}

CLI:

topolo actions validate app_topolo_auth.user_permission_overrides.list --data @payload.json --json
topolo actions plan app_topolo_auth.user_permission_overrides.list --data @payload.json --json
topolo actions call app_topolo_auth.user_permission_overrides.list --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.user_permission_overrides.list",
    "input": {
      "userId": "usr_managed"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "User permission overrides fetched",
  "data": {
    "userId": "usr_managed",
    "orgId": null,
    "appId": null,
    "overrides": [
      {
        "id": "upo_FfLusJrOwlvd",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.read",
        "effect": "allow",
        "expires_at": null,
        "created_at": 1790899200
      },
      {
        "id": "upo_E-G6cLsM_852",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.read",
        "effect": "allow",
        "expires_at": null,
        "created_at": 1790899200
      },
      {
        "id": "upo_JnwqYI7Kow_Z",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.read",
        "effect": "deny",
        "expires_at": null,
        "created_at": 1790899200
      },
      {
        "id": "upo_7xT5fqF91l9B",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.write",
        "effect": "allow",
        "expires_at": 1790899199,
        "created_at": 1790899200
      },
      {
        "id": "upo_nNFZ7808mFji",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.write",
        "effect": "allow",
        "expires_at": 0,
        "created_at": 1790899200
      }
    ]
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Self can select another recorded organization membership

Input · payload.json:

{
  "userId": "usr_managed",
  "orgId": "org_other",
  "appId": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.user_permission_overrides.list --data @payload.json --json
topolo actions plan app_topolo_auth.user_permission_overrides.list --data @payload.json --json
topolo actions call app_topolo_auth.user_permission_overrides.list --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.user_permission_overrides.list",
    "input": {
      "userId": "usr_managed",
      "orgId": "org_other",
      "appId": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "User permission overrides fetched",
  "data": {
    "userId": "usr_managed",
    "orgId": "org_other",
    "appId": "app_topolo_campaigns",
    "overrides": []
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

After deleting one allow, duplicate allow and deny rows remain

Input · payload.json:

{
  "userId": "usr_managed",
  "orgId": "org_example",
  "appId": "app_topolo_campaigns"
}

CLI:

topolo actions validate app_topolo_auth.user_permission_overrides.list --data @payload.json --json
topolo actions plan app_topolo_auth.user_permission_overrides.list --data @payload.json --json
topolo actions call app_topolo_auth.user_permission_overrides.list --data @payload.json --json

MCP call after validation and plan review:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_auth.user_permission_overrides.list",
    "input": {
      "userId": "usr_managed",
      "orgId": "org_example",
      "appId": "app_topolo_campaigns"
    }
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "User permission overrides fetched",
  "data": {
    "userId": "usr_managed",
    "orgId": "org_example",
    "appId": "app_topolo_campaigns",
    "overrides": [
      {
        "id": "upo_E-G6cLsM_852",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.read",
        "effect": "allow",
        "expires_at": null,
        "created_at": 1790899200
      },
      {
        "id": "upo_JnwqYI7Kow_Z",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.read",
        "effect": "deny",
        "expires_at": null,
        "created_at": 1790899200
      },
      {
        "id": "upo_7xT5fqF91l9B",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.write",
        "effect": "allow",
        "expires_at": 1790899199,
        "created_at": 1790899200
      },
      {
        "id": "upo_nNFZ7808mFji",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.write",
        "effect": "allow",
        "expires_at": 0,
        "created_at": 1790899200
      },
      {
        "id": "upo_D-HNMcoMC0yj",
        "user_id": "usr_managed",
        "organization_id": "org_example",
        "app_id": "app_topolo_campaigns",
        "permission_name": "campaigns.write",
        "effect": "allow",
        "expires_at": null,
        "created_at": 1790899200
      }
    ]
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Verify the result

Keep each row id alongside user_id, organization_id, app_id, permission_name, effect and expires_at. Use exact organization/application filters for the intended decision.
Read user_permissions.get for that user/organization/application and independently test the intended protected application action; the stored list alone does not prove effective access.

Errors and recovery

Organization not belonging to target identity is refused

Captured local refusal · HTTP 400:

{
  "input": {
    "userId": "usr_managed",
    "orgId": "org_missing",
    "appId": "app_topolo_campaigns"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Target user does not belong to the provided organization",
      "code": "VALIDATION_ERROR",
      "details": {
        "orgId": true
      },
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Another organization admin cannot read this managed user overrides

Captured local refusal · HTTP 401:

{
  "input": {
    "userId": "usr_managed",
    "orgId": "org_example",
    "appId": "app_topolo_campaigns"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Access denied: You can only view your own overrides",
      "code": "AUTH_ERROR",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Missing user is not an empty override list

Captured local refusal · HTTP 404:

{
  "input": {
    "userId": "usr_missing"
  },
  "response": {
    "success": false,
    "error": {
      "message": "User not found",
      "code": "NOT_FOUND",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Anonymous override discovery is refused

Captured local refusal · HTTP 401:

{
  "input": {
    "userId": "usr_managed",
    "orgId": "org_example",
    "appId": "app_topolo_campaigns"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Access token required",
      "code": "AUTH_ERROR",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Published recovery guidance

VALIDATION_ERROR (HTTP 400): Correct fields and resolve the target organization membership through authorized identity discovery. An app permission name must be declared; stored-row metadata does not assign an app entitlement.
AUTH_ERROR (HTTP 401): Verify approved identity, organization-admin role, exact row organization authority and transport. Authenticated role/authority denial also uses 401; do not assume expiry or switch credential context automatically.
NOT_FOUND (HTTP 404): Refresh the exact user/organization/application row list. Missing target or already-deleted/exact-user-mismatched override is not a successful new deletion.
SERVER_ERROR (HTTP 500): Preserve the original error and rediscover current rows before reviewing a retry. Unknown permission names, token exceptions or storage errors are possible. Creation has no idempotency key; blindly retrying an unknown outcome can duplicate an override.

Recovery boundaries

Read-only. Keep security configuration within the approved user workflow and preserve conflicting/duplicate rows for deliberate review rather than deleting them automatically.

Discovery and evidence

This record belongs to app_topolo_auth. Local tests prove real canonical override SQL, declared permission validation and exact stored-row organization authority with simulated tokens, target memberships and a permission catalog partition. They do not prove actual app assignment, effective access enforcement, live permissions, deployment or production completion.