Explain current resource permissions

Requires resource, workspace, or organization administration to inspect others. Callers may inspect themselves on resources they can read. Inspects a known person, API key, or app using current ownership, inheritance and active grants. Optional app context intersects both grant levels. Other-key inspection requires organization administration. Hosted app, delegated action, MCP, and connector sessions are excluded. This is a resource-permission assessment, not a simulated login or proof of operation readiness; publication, invocation, source bindings and session policy retain their own checks.

POST/v1/permissions/inspect

betaauthenticatedorganization

When to use

Explain current permissions on a known resource for a person, API key, or app.

For agents

Inspecting others requires administration of the resource or its workspace/organization. Callers may inspect themselves on resources they can read. Other API keys require organization administration; keys may inspect themselves under resource admin authority. An optional applicationId intersects caller and app grants. Evidence lists current whole-resource grants and ownership (not expired grants). Inspection does not grant access, impersonate the principal, validate a login session, or prove an action can run. Operation policy, published bindings, and readiness are checked when used.

Example

typescript

import { PermuteClient } from '@permute/sdk';

const orgClient = new PermuteClient({
  apiKey: process.env.PERMUTE_API_KEY!,
});

const result = await orgClient.permissions.inspect({
  "resourceId": "dbas_abcdefghijklmnopqrstuvwx",
  "principal": {
    "type": "user",
    "id": "user_abcdefghijklmnopqrstuvwx"
  }
});

Request body

json

{
  "resourceId": "dbas_abcdefghijklmnopqrstuvwx",
  "principal": {
    "type": "user",
    "id": "user_abcdefghijklmnopqrstuvwx"
  }
}

Response

json

{
  "data": {
    "resourceId": "dbas_abcdefghijklmnopqrstuvwx",
    "resourceType": "database",
    "workspaceId": "wksp_abcdefghijklmnopqrstuvwx",
    "principal": {
      "type": "user",
      "id": "user_abcdefghijklmnopqrstuvwx"
    },
    "principalAccess": {
      "level": "admin",
      "sources": [
        {
          "kind": "owner",
          "level": "admin"
        }
      ],
      "restriction": null
    },
    "application": null,
    "effectiveLevel": "admin",
    "restrictions": [],
    "evaluatedAt": "2026-10-28T12:00:00.000Z"
  }
}