# Webiny API Permissions

Schema-based permission system for API features.

- Repository: https://github.com/webiny/webiny-js (8051 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add webiny/webiny-js --skill webiny-api-permissions -g -a claude-code -y`
Codex: `npx skills add webiny/webiny-js --skill webiny-api-permissions -g -a codex -y`
Cursor: `npx skills add webiny/webiny-js --skill webiny-api-permissions -g -a cursor -y`
Gemini CLI: `npx skills add webiny/webiny-js --skill webiny-api-permissions -g -a gemini-cli -y`

## Description

Schema-based permission system for API features. Use this skill when implementing authorization in use cases, defining permission schemas with createPermissionSchema, creating injectable permissions via createPermissionsAbstraction/createPermissionsFeature, checking read/write/delete/publish permissions, handling own-record scoping, or testing permission scenarios. Covers the full pattern from schema definition to use case integration to test matrices.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# API Permissions

## Overview

Permissions follow two layers: **domain** (schema) and **features** (DI abstractions + feature registration). Each package declares a permission schema and gets a typed `Permissions` abstraction injectable into use cases via DI. Methods like `canRead`, `canEdit`, `canDelete`, `canPublish`, `onlyOwnRecords` replace manual `identityContext.getPermission()` calls.

## Layer 1: Domain, Permission Schema

Define the schema in `src/domain/permissionsSchema.ts`:

```ts
import { createPermissionSchema } from "webiny/api/security";

export const SM_PERMISSIONS_SCHEMA = createPermissionSchema({
  prefix: "sm",
  fullAccess: true,
  entities: [
    {
      id: "product",
      permission: "sm.product",
      scopes: ["full", "own"],
      actions: [{ name: "rwd" }, { name: "pw" }]
    },
    {
      id: "settings",
      permission: "sm.settings",
      scopes: ["full"]
    }
  ]
});
```

The schema MUST use `as const` inference (handled by `createPermissionSchema`) for TypeScript to narrow entity IDs in method signatures.

### Schema Fields

The rest: https://github.com/webiny/webiny-js/blob/HEAD/skills/user-skills/api/permissions/SKILL.md