# vtex-io-rbac

Walks you through locking down VTEX IO app routes and resources: role policies, resource policies, VRN principals and @auth directives.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 737 installs · ★ 46
- Author: vtex
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/vtex/skills/tree/HEAD/skills/vtex-io-rbac/SKILL.md
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/skills/vtex-io-rbac

## What it does

This skill covers access control for VTEX IO apps. It explains when to reach for role-based policies in `policies.json` versus resource-based ones in `service.json`, how VRN principals are written, and where the GraphQL `@auth` directive fits.

The rule that trips people up: role-based policies only cover app-to-app calls. If users or API-key integrations need to hit your endpoint, you need resource-based policies in `service.json` with the route set to `"public": false`. Ship only `policies.json` and those callers get 403 Forbidden, because role-based policies never evaluate their tokens. Worth checking if a private route suddenly rejects your admin users.

Deny beats allow. A broad `allow` for `app/*` plus a narrow `deny` blocks the named app, which is what you want. Flip it — broad `deny`, narrow `allow` — and everything is blocked, including the app you meant to let through. The skill stays out of general service architecture, payment PCI security and route prefix or CDN behavior.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-rbac -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/vtex-io-rbac/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/vtex-io-rbac/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-rbac -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/vtex-io-rbac/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-rbac -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/vtex-io-rbac/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills vtex-io-rbac
```

2. **Manually: put the files in place**
- File: `.github/skills/vtex-io-rbac/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-rbac -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-rbac
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/vtex-io-rbac/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-rbac -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/vtex/skills/tree/HEAD/skills/vtex-io-rbac/SKILL.md

## When to use it
- pick between role-based and resource-based policies
- expose a REST endpoint to users and API keys safely
- wire up GraphQL authorization with the `@auth` directive
- write VRN principals without syntax mistakes
- track down a 403 Forbidden on a private route

## Example prompts
- Secure the `/_v/private/my-app/orders` route so only admins and one partner app can call it
- Why does my private endpoint return 403 for users when `policies.json` is already set up?
- Add the `@auth` directive to the orders query in my GraphQL schema

## Similar
- [access-control-rbac](https://affpapa.org/en/nevibecode/skills/access-control-rbac.md) — skill · 757 installs
- [api-sec](https://affpapa.org/en/nevibecode/skills/api-sec.md) — skill · 3900 installs
- [conducting-api-security-testing](https://affpapa.org/en/nevibecode/skills/conducting-api-security-testing.md) — skill · 643 installs
- [api-audit](https://affpapa.org/en/nevibecode/skills/api-audit.md) — skill · 482 installs
- [api-and-interface-design](https://affpapa.org/en/nevibecode/skills/api-and-interface-design.md) — skill · 62600 installs
- [api-design-principles](https://affpapa.org/en/nevibecode/skills/api-design-principles.md) — skill · 30348 installs

From the same set: [vtex/skills](https://affpapa.org/en/nevibecode/by/vtex/skills.md) — 8 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md