Skip to main content

Onboard a New Developer

TL;DR

Invite a new developer, assign them to a tenant, attach role-specific bundles, and have them approve their device — all in under 5 minutes.

Why this matters

  • Reduces onboarding time and mistakes that leak secrets.
  • Ensures least-privilege access via bundles.
  • Provides an audit trail for who accessed what and when.

When to use

  • New hires, contractors, or temporary contributors who need dev credentials.

Step-by-step

  1. Create or verify a tenant (optional):
# Admin: create tenant (if multi-tenancy used)
envcat tenant create my-project
  1. Create role-specific bundles (Admin UI or API):
# Create bundle via API
curl -X POST http://localhost:8888/api/v1/bundles \
  -H "Content-Type: application/json" \
  -d '{"name":"my-project/dev", "description":"Dev bundle for backend + frontend"}'
  1. Invite the user and assign role:
# Invite user
envcat user invite alice@example.com --role Developer --tenant my-project
  1. Ask the new developer to install the CLI and request the bundle:
# Install CLI (SaaS)
# Use the public installer from env.cat for users of the hosted service
curl -fsSL https://env.cat/cli/install.sh | sh

# OR: Install CLI (Local development)
# If you're running EnvCat locally during development, use the local installer or build from source
# Example: run from the test container that includes the CLI
# docker compose run --rm tests bash
# envcat get --bundle my-project/dev --api-base http://localhost:8888

# Request bundle (SaaS)
# When targeting the hosted service, use the public API base at https://env.cat
envcat get --bundle my-project/dev --api-base https://env.cat

# Request bundle (Local)
# When testing locally, point the CLI at your local BFF (Next.js) on port 8888
envcat get --bundle my-project/dev --api-base http://localhost:8888
  1. Developer approves in browser (select keys and Approve & Encrypt). Once approved, they can run:
# Load into current shell (SaaS)
# Use the hosted API base when your team uses env.cat
eval "$(envcat get --bundle my-project/dev --api-base https://env.cat)"

# Load into current shell (Local)
# For local development, point at localhost
eval "$(envcat get --bundle my-project/dev --api-base http://localhost:8888)"

Examples

  • Invite multiple users by CSV via Admin UI import.
  • Pre-create demo keys for designers with placeholder values.

Best practices & pitfalls

  • Keep bundles small and role-focused — fewer keys reduce risk.
  • Use demo bundles for designers with non-production keys.
  • Rotate keys after hiring changes or role changes.

Troubleshooting

Problem: CLI shows QR but browser shows 404 on /approve

Solution: Verify web UI is running on port 8888 and request ID is correct. Check API logs for incoming request.

Next steps

  • See Designer Demo recipe: ../recipes/designer-demo.md
  • See AI-safe Keys recipe: ../recipes/ai-safe-keys.md