vtex-io-rbac — Claude Code skill: VTEX IO access control
Walks you through locking down VTEX IO app routes and resources: role policies, resource policies, VRN principals and @auth directives.
npx skills add vtex/skills --skill vtex-io-rbac -a claude-codeWhat vtex-io-rbac 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.
What it helps with
- pick between role-based and resource-based policies
- expose a REST endpoint to users and API keys safely
- wire up GraphQL authorization with the
@authdirective - write VRN principals without syntax mistakes
- track down a 403 Forbidden on a private route
Example prompts for the agent
- Secure the
/_v/private/my-app/ordersroute so only admins and one partner app can call it - Why does my private endpoint return 403 for users when
policies.jsonis already set up? - Add the
@authdirective to the orders query in my GraphQL schema
How to install vtex-io-rbac
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-rbac -a claude-code2Manually: put the files in place
~/.claude/skills/vtex-io-rbac/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/vtex-io-rbac/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-rbac -a codex2Manually: put the files in place
.agents/skills/vtex-io-rbac/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-rbac -a cursor2Manually: put the files in place
.cursor/skills/vtex-io-rbac/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills vtex-io-rbac2Manually: put the files in place
.github/skills/vtex-io-rbac/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-rbac -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-rbacManually: put the files in place
.devin/skills/vtex-io-rbac/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill vtex-io-rbac -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about vtex-io-rbac
How do I install vtex-io-rbac in Claude Code?
Run npx skills add vtex/skills --skill vtex-io-rbac -a claude-code. The skill lands in ~/.claude/skills/vtex-io-rbac/SKILL.md.
What does vtex-io-rbac do?
It helps you choose between role-based and resource-based access policies, set up VRN principals and add GraphQL authorization. It also explains why a route returns 403.
How do role-based and resource-based policies differ?
Role-based policies in policies.json only cover app-to-app calls, and the calling app declares the policy in its manifest.json. Resource-based policies in service.json open a route to users and API keys, with no declaration needed.
