Accounts & Developer Mode

Last updated: 2026-05-07 06:53:50

Accounts & Developer Mode¶

Huitzo uses a unified account model where all users start as consumers and can optionally enable Developer Mode to build and publish Intelligence Packs.

Account Model Overview¶

┌─────────────────────────────────────────────────────────┐
│  User Account                                           │
│  ├── Consumer Mode (default)                            │
│  │   └── Dashboard Hub, installed packs, WebCLI         │
│  │                                                      │
│  └── Developer Mode (opt-in)                            │
│      └── + SDK, CLI, pack publishing, @scope            │
└─────────────────────────────────────────────────────────┘

Consumer Mode (Default)¶

When you create a Huitzo account, you start in Consumer Mode. This provides access to:

Feature	Description
Dashboard Hub	Central interface for all your installed packs
Pack Marketplace	Browse and install Intelligence Packs
WebCLI	Run commands directly from the Dashboard
Pack Settings	Configure installed packs

What you can do: - Sign up and access the Dashboard - Browse and install packs from the marketplace - Run commands via WebCLI in the Dashboard - Manage your installed packs and settings

What you cannot do (until Developer Mode enabled): - Download the SDK - Authenticate with the CLI - Publish packs to the marketplace - Claim an @scope for your organization

Developer Mode (Opt-in)¶

Developer Mode unlocks the full platform capabilities for building and publishing Intelligence Packs.

Enabling Developer Mode¶

Step 1: Navigate to Settings

In the Dashboard, go to Settings > Account > Developer Mode.

Step 2: Create or Join an Organization

Developer Mode requires an organization. You can: - Create a new organization with a unique slug - Join an existing organization via invite

Step 3: Confirm Activation

Once confirmed, your account gains Developer Mode capabilities.

What Developer Mode Unlocks¶

Feature	Description
SDK Access	Download `huitzo-sdk` package
CLI Authentication	Use `huitzo login` to authenticate
Pack Publishing	Publish packs under your `@scope`
Organization Scope	Your org's `@scope` for namespacing
Marketplace Selling	Set pricing and receive payouts

API: Enable Developer Mode¶

POST /api/v1/account/developer-mode
Authorization: Bearer {token}
Content-Type: application/json

{
  "organization": {
    "name": "Acme Corp",
    "slug": "acme"
  }
}

Response:

{
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "mode": "developer"
    },
    "organization": {
      "id": "org_xyz789",
      "name": "Acme Corp",
      "slug": "acme",
      "scope": "@acme"
    },
    "message": "Developer Mode enabled. You can now use the SDK and CLI."
  }
}

Organizations¶

Organizations are the ownership unit for packs. Every pack is published under an organization's @scope.

Organization Structure¶

Organization: Acme Corp
├── Slug: acme
├── Scope: @acme
├── Members:
│   ├── [email protected] (owner)
│   ├── [email protected] (admin)
│   └── [email protected] (member)
└── Packs:
    ├── @acme/claims-processor
    ├── @acme/billing-tools
    └── @acme/analytics

Roles¶

Role	Permissions
Owner	Full control, billing, delete org
Admin	Manage members, publish packs
Member	Publish packs under org scope

Creating an Organization¶

Organizations are created when enabling Developer Mode:

POST /api/v1/account/developer-mode
{
  "organization": {
    "name": "My Company",
    "slug": "my-company"
  }
}

Or by creating a new organization directly (for users already in Developer Mode):

POST /api/v1/organizations
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "New Organization",
  "slug": "new-org"
}

Inviting Members¶

POST /api/v1/organizations/{org_id}/invite
Authorization: Bearer {token}
Content-Type: application/json

{
  "email": "[email protected]",
  "role": "member"
}

Scope Ownership¶

When Developer Mode is enabled, your organization receives a unique @scope derived from the organization slug.

How Scope is Assigned¶

User enables Developer Mode
    ↓
Creates/joins Organization (slug: "acme")
    ↓
Scope assigned: @acme
    ↓
All packs published as: @acme/{pack-name}

Slug Validation Rules¶

Rule	Requirement
Length	2-39 characters
Characters	Lowercase letters, numbers, hyphens
Start/End	Cannot start or end with hyphen
Uniqueness	Globally unique in Cloud deployment

Valid examples: - acme - my-company - startup-2024 - a1b2c3

Invalid examples: - A (too short) - My-Company (uppercase not allowed) - -acme (starts with hyphen) - acme- (ends with hyphen)

Reserved Scopes¶

The following scopes are reserved and cannot be claimed:

Scope	Reserved For
`@huitzo.*`	Official Huitzo packs
`@system.*`	Platform system commands
`@admin.*`	Platform administration

Cloud vs Self-Hosted Scope Uniqueness¶

Deployment	Scope Uniqueness
Cloud (SaaS)	Globally unique across all users
Self-Hosted	Unique within that instance only

Mode Transitions¶

Consumer → Developer¶

The typical journey from consumer to developer:

1. Sign up → Consumer Mode
   └── Uses Dashboard, installs packs

2. Wants to build a pack
   └── Enables Developer Mode in Settings

3. Creates/joins organization
   └── Receives @scope

4. Downloads SDK/CLI
   └── Runs: huitzo login

5. Builds and publishes pack
   └── Published as @org-slug/pack-name

Check Current Mode¶

GET /api/v1/account/mode
Authorization: Bearer {token}

Response (Consumer):

{
  "data": {
    "mode": "consumer",
    "developer_mode_available": true
  }
}

Response (Developer):

{
  "data": {
    "mode": "developer",
    "organization": {
      "id": "org_xyz789",
      "name": "Acme Corp",
      "slug": "acme",
      "scope": "@acme"
    }
  }
}

Self-Hosted Accounts¶

Self-hosted deployments have a simplified account model:

Feature	Cloud	Self-Hosted
Marketplace access	Yes	No
Third-party packs	Yes	No (internal only)
Developer publishing	Yes	No (local install only)
Stripe integration	Yes	No
Platform fees	Tiered	None

Self-Hosted Use Cases¶

Enterprise deploys self-hosted instance
    ↓
Builds internal packs (not published to marketplace)
    ↓
Installs packs locally via CLI or direct upload
    ↓
No Stripe, no fees, no external dependencies

Quick Reference¶

Registration Flow¶

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "securepassword",
  "name": "Jane Smith"
}