Skip to main content

Roles

TL;DR

Roles let you group users by responsibility (Developer, Designer, Service) and grant them access to specific bundles. Use roles to enforce least-privilege access and simplify onboarding.

Why roles matter

  • Reduce human error: assign permissions to a role once instead of many individual users.
  • Enforce least privilege: give only the bundles a role needs.
  • Improve audits: track access by role and reason.

Common roles (examples)

  • Developer — Access to dev/test bundles and service credentials.
  • Designer — Access to demo bundles with placeholder values.
  • Service / MCP — Machine accounts that request ephemeral keys for CI or background jobs.
  • Admin — Manage bundles, users, and tenant settings (should be limited).

How to use roles

  1. Create a role in the Admin UI or via the API.
# Example (API)
curl -X POST http://localhost:8888/api/v1/roles -H "Content-Type: application/json" \
  -d '{"name":"Designer","description":"Designers: demo bundles only"}'

  1. Attach bundle-level policies to the role (UI or API). For example, allow read for my-project/demo and deny reveal.

  2. Invite users and assign roles during onboarding.

Best practices

  • Prefer role-based access over per-user grants for team-based permissions.
  • Keep service accounts separate from human roles; require short TTLs and scoped scopes for services.
  • Document role-to-bundle mappings in your team onboarding playbook.

Pitfalls

  • Over-permissive roles: avoid broad Admin roles for day-to-day tasks.
  • Role creep: periodically review roles and remove unused permissions.

Next steps

  • See Onboarding recipe for a sample flow: ../recipes/onboard-new-dev.md
  • Learn how bundles map to roles: ../concepts/bundles.md