Creating a Workspace

A workspace is your organization's private environment for managing Flutter packages, team members, and access controls.

What is a Workspace?

A workspace provides:

Isolated package registry - Your private packages separate from other organizations
Team collaboration - Invite members with specific roles
Access control - Fine-grained permissions via RBAC
Usage tracking - Monitor downloads and storage
Billing management - Separate billing per workspace

Creating Your First Workspace

Create an account if you don't have one:

curl -X POST https://registry.yourcompany.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "secure_password",
    "name": "Your Name"
  }'

Response:

{
  "id": "usr_c0s6t7vjnb0c73f5g6eg",
  "email": "you@company.com",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Create Workspace

curl -X POST https://registry.yourcompany.com/v1/workspaces \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-corp",
    "display_name": "ACME Corporation",
    "description": "Private packages for ACME Corp engineering teams"
  }'

Response:

{
  "id": "ws_c0s6t7vjnb0c73f5g6eg",
  "name": "acme-corp",
  "display_name": "ACME Corporation",
  "description": "Private packages for ACME Corp engineering teams",
  "owner_id": "usr_c0s6t7vjnb0c73f5g6eg",
  "created_at": "2025-01-10T10:00:00Z",
  "plan": "free"
}

Verify Workspace

List your workspaces:

curl https://registry.yourcompany.com/v1/me/workspaces \
  -H "Authorization: Bearer YOUR_TOKEN"

🎉 Workspace created! You're now the workspace owner with full permissions.

Workspace Configuration

Basic Settings

# Update workspace details
curl -X PATCH https://registry.yourcompany.com/v1/workspaces/ws_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "ACME Engineering",
    "description": "Updated description",
    "website": "https://acme.com"
  }'

Workspace Namespace

Your workspace name becomes the namespace for packages:

https://registry.yourcompany.com/workspaces/acme-corp/packages/my-package

Note: Workspace names are immutable after creation. Choose wisely!

Multiple Workspaces

Create separate workspaces for different teams or projects:

company/
├── frontend-team/
│   ├── ui_components
│   └── shared_widgets
├── backend-team/
│   └── api_client
└── mobile-team/
    ├── auth_package
    └── analytics

Use Cases

By Team:

Frontend Team Workspace
Backend Team Workspace
Mobile Team Workspace

By Project:

Project Alpha Workspace
Project Beta Workspace

By Environment:

Development Workspace
Staging Workspace
Production Workspace

Workspace Plans

Choose a plan that fits your needs:

Plan	Packages	Storage	Members	Price
Free	5	5 GB	5	$0/month
Pro	50	100 GB	25	$49/month
Enterprise	Unlimited	Unlimited	Unlimited	Custom

Upgrading Plan

curl -X POST https://registry.yourcompany.com/v1/workspaces/ws_ID/subscription \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "pro",
    "billing_email": "billing@company.com"
  }'

See Billing Plans for detailed comparison.

Workspace Settings

Default Package Visibility

Set default visibility for new packages:

curl -X PATCH https://registry.yourcompany.com/v1/workspaces/ws_ID/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_package_visibility": "private",
    "require_2fa": true,
    "allowed_domains": ["company.com"]
  }'

Security Settings

{
  "require_2fa": true,              // Require 2FA for all members
  "allowed_domains": ["company.com"], // Restrict member emails
  "ip_allowlist": ["203.0.113.0/24"], // IP restrictions
  "audit_log_retention": 90         // Days to retain audit logs
}

Workspace Roles

When you create a workspace, you automatically become the Owner with full permissions. You can then invite team members with different roles.

Default Roles

Role	Description	Permissions
Owner	Full control	Everything
Developer	Publish and manage packages	Create, edit, delete packages
Tester	Download and test packages	Read and download packages
Viewer	Read-only access	View package metadata

See Roles & Permissions for details.

Workspace URLs

After creation, your workspace is accessible at:

Registry: https://registry.yourcompany.com
Workspace: https://registry.yourcompany.com/workspaces/acme-corp
Packages: https://registry.yourcompany.com/workspaces/acme-corp/packages

Best Practices

1. Naming Convention

Use clear, descriptive names:

# ✓ Good
acme-frontend
acme-mobile-team
project-alpha

# ✗ Bad
ws1
test
temp

2. One Workspace Per Team/Project

Don't mix unrelated packages:

# ✓ Good structure
- frontend-workspace (UI packages)
- backend-workspace (API packages)

# ✗ Bad structure
- everything-workspace (all packages mixed)

3. Document Workspace Purpose

Add clear descriptions:

{
  "name": "mobile-team",
  "display_name": "Mobile Engineering Team",
  "description": "Shared Flutter packages for iOS and Android apps"
}

4. Set Up Billing Early

Configure billing before hitting limits:

# Set billing email
curl -X PATCH https://registry.yourcompany.com/v1/workspaces/ws_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"billing_email":"billing@company.com"}'

Workspace Management

View Workspace Details

curl https://registry.yourcompany.com/v1/workspaces/ws_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

List All Packages

curl https://registry.yourcompany.com/v1/workspaces/ws_ID/packages \
  -H "Authorization: Bearer YOUR_TOKEN"

View Usage Statistics

curl https://registry.yourcompany.com/v1/workspaces/ws_ID/stats \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "packages": 12,
  "versions": 45,
  "storage_used": "2.5 GB",
  "downloads_this_month": 1523,
  "members": 8
}

Transferring Ownership

Transfer workspace ownership to another member:

curl -X POST https://registry.yourcompany.com/v1/workspaces/ws_ID/transfer \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_owner_id": "usr_NEW_OWNER_ID"
  }'

Warning: This action is irreversible. The new owner will have full control.

Deleting a Workspace

Danger Zone: Deleting a workspace is permanent and will delete all packages, versions, and data.

curl -X DELETE https://registry.yourcompany.com/v1/workspaces/ws_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm": "acme-corp"}'  # Must type workspace name

Troubleshooting

"Workspace name already taken"

Workspace names must be globally unique:

# Try alternative names
acme-corp-engineering
acme-engineering
acme-packages

"Forbidden"

You need workspace owner permissions to modify settings:

# Check your role
curl https://registry.yourcompany.com/v1/workspaces/ws_ID/members/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Next Steps

Managing Members - Invite your team
Roles & Permissions - Configure access control
Billing Plans - Choose the right plan

Questions? See FAQ or contact support.

On this page