Skip to content
HomeStar Docs

Onboard a Brokerage Owner

This is the manual handoff that turns a freshly-created brokerages row into a real human who can sign in. It has to happen out-of-band because Authentik account creation is gated by an admin login that isn’t wired into the HomeStar admin UI.

Prerequisites

Section titled “Prerequisites”
  • Authentik admin access at https://auth.supported.systems
  • Postgres access on the prod host (ssh deploy@homestar.ink)
  • The owner’s confirmed email address — must come from the brokerage domain, not a guess based on the brokerage name

Steps

Section titled “Steps”

  1. Create the Authentik user

    Log in to https://auth.supported.systems as akadmin.

    Navigate to Directory → Users → Create.

    Fields:

    • Username: a stable handle, e.g. joe.kroetch (lowercase, no spaces). This is what shows in the Authentik admin and in oidc_user_id once the user logs in.
    • Name: full display name, e.g. Joe Kroetch
    • Email: confirmed email, e.g. joe@kroetchpropertygroup.com
    • Path: users
    • Type: Internal

    Click Create.

  2. Set or invite a password

    On the new user’s page, Reset Password → either:

    • Set a temporary password and share it through a secure channel (1Password, password-protected email, in person), OR
    • Click Set password → Send password reset email to let the owner pick their own password.

    The “send reset email” path is preferred — Authentik handles the token expiry and the user never sees an admin-set string.

  3. Add to the brokerage-owner group

    On the user’s page, Groups tab → Add to group → pick the group whose name contains brokerage_owner or owner. The HomeStar OIDC fuzzy matcher (in idx-api/src/idx_api/auth.py) resolves any group name containing one of those substrings to role=brokerage_owner.

    If no such group exists, create one in Directory → Groups named homestar-brokerage_owner with no parent. Future owners share this group.

  4. Create the user row in the HomeStar database

    The Authentik account proves who logs in. The users row in our DB scopes them to a specific brokerage and role. Both are needed.

    Terminal window
    ssh deploy@homestar.ink
    cd /home/deploy/homestar
    docker compose exec -T postgres psql -U mlsgrid -d mlsgrid <<SQL
    INSERT INTO users (email, role, agent_id, brokerage_id, created_at, updated_at)
    VALUES (
      'joe@kroetchpropertygroup.com',
      'brokerage_owner',
      1,           -- their agent_id, if they have an agents row; else NULL
      2,           -- their brokerage_id
      NOW(), NOW()
    )
    RETURNING id, email, role, agent_id, brokerage_id;
    SQL

    Replace the email, agent_id, and brokerage_id with real values. The query is idempotent on email (UNIQUE index) — re-running will fail with a constraint violation rather than create a duplicate, which is what we want.

  5. Verify the login flow

    Have the owner navigate to https://app.homestar.ink/admin and click “Sign In to Dashboard.” They’ll be redirected to Authentik, complete password setup if invited, then bounce back to /admin authenticated as brokerage_owner.

    On the first successful login, our auth handler patches their users.oidc_user_id to match the Authentik subject claim. Subsequent logins resolve via that ID instead of the email match — slightly faster and survives email changes.

Common failure modes

Section titled “Common failure modes”
  • “Site configuration not available” after login: the users.brokerage_id doesn’t match an existing brokerages row or the brokerage’s slug isn’t routable to a hostname yet. Check brokerage_domains and the caddy-docker-proxy advertiser logs.
  • 403 on owner-only endpoints: the Authentik group name doesn’t include brokerage_owner or owner. The fuzzy matcher classified them as a lower role (probably agent). Add the group or rename it.
  • Login succeeds but users.role reads agent: the OIDC token’s groups claim is empty. In Authentik, edit the homestar-ink provider → Scopes → ensure the groups scope is mapped onto the access token.

See Also

Section titled “See Also”