Create or replace an explicit permission grant

Requires resource access-management authority or the applicable workspace/organization administration. A matching subject/resource/scope grant is updated in place, replacing its level, operations and expiry; omitted expiry clears it. Named operations are checked independently and cannot exceed the caller's authority. Omitting operations uses the resource’s level-based grant behavior. Subjects may be people, API keys, apps, workspaces or organizations. A user email creates a pre-grant without sending an invitation. Wildcard (*, *) grants require organization administration. New grants support whole resources and resource-type wildcards, with optional expiry. Table, row, and column scopes are not supported by current source query APIs, including databases, datasets, connectors, and operation outputs. Existing scoped app grants can be revoked with level: null and their original subResourceId; other scoped grants use the permission deletion API. Hosted app, delegated action, MCP and connector sessions are excluded.

POST/v1/permissions

betaauthenticatedorganization

When to use

Give a person, API key, app or membership principal access to a resource.

For agents

Uses the same authorization as Give access. POST replaces an existing matching subject/resource/scope grant, including expiry; omitted expiry clears it. Named operations are independent and cannot exceed the caller’s authority. For additive changes, read and reconcile the existing grant first. Granting a user email does not send an invitation. API keys and apps need their own grants; creator access does not transfer.

Example

typescript

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

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

const result = await orgClient.permissions.create({
  "principalType": "apiKey",
  "principalId": "apikey_example",
  "resourceId": "dbas_abcdefghijklmnopqrstuvwx",
  "resourceType": "database",
  "level": "read"
});

Request body

json

{
  "principalType": "apiKey",
  "principalId": "apikey_example",
  "resourceId": "dbas_abcdefghijklmnopqrstuvwx",
  "resourceType": "database",
  "level": "read"
}

Response

json

{
  "data": {
    "id": "perm_abcdefghijklmnopqrstuvwx",
    "principalType": "apiKey",
    "principalId": "apikey_example",
    "resourceId": "dbas_abcdefghijklmnopqrstuvwx",
    "resourceType": "database",
    "subResourceId": null,
    "level": "read",
    "operations": null,
    "organizationId": "org_abcdefghijklmnopqrstuvwx",
    "workspaceId": "wksp_abcdefghijklmnopqrstuvwx",
    "grantedBy": "user_abcdefghijklmnopqrstuvwx",
    "expiresAt": null,
    "createdAt": "2026-10-30T12:00:00.000Z",
    "updatedAt": "2026-10-30T12:00:00.000Z"
  }
}