Skip to main content

People & Authentication Deployment

Deploy compatible core-server and core-app versions together. The people and authentication features require PostgreSQL and the server's method discovery, person access and identity metadata endpoints. The app provides administration under Settings → People; see People & Roles.

Configure authentication emails​

Add the following settings to the server YAML, using your frontend URL and mail service details:

externalUrl: https://app.example.com/hivekit/
displayedAppName: Mine Operations
smtpHost: smtp.example.com
smtpPort: "587"
smtpUser: smtp-user
smtpPassword: CHANGE_ME
fromEmailAddress: no-reply@example.com

externalUrl must include any frontend subpath. HTTPS is required except for loopback development. Invalid configured URLs fail startup validation; a missing URL prevents invitation, password setup and recovery requests. The environment override is hkt_externalUrl; the former HIVEKIT_AUTH_APP_URL is no longer read.

displayedAppName sets the name used in authentication email subjects and bodies and defaults to Hivekit when blank or omitted. Its environment override is hkt_displayedAppName. Authentication emails include HTML and plain-text alternatives.

Links place one-use credentials in the URL fragment. Core-app removes the fragment after reading and verifies the link before displaying the account email. The server uses the configured frontend URL rather than a request host or client redirect. Users complete setup/reset through the linked password form; manual challenge entry is not supported.

Browser origins and cookies​

Local browser sessions use the HttpOnly, SameSite=Lax hkt_session cookie. On direct TLS it is Secure. Behind a TLS-terminating proxy, set HIVEKIT_AUTH_COOKIE_SECURE=true.

Authentication rejects browser origins different from the API origin unless explicitly allowed. For a separately hosted frontend, set HIVEKIT_AUTH_ALLOWED_ORIGINS to a comma-separated list of exact trusted origins, including scheme and non-default port, for example https://app.example.com,https://operations.example.com:8443. Keep enableCors: true. General CORS configuration does not override the authentication origin check.

For development, matching loopback hosts and schemes can use different ports automatically: http://localhost:8080 can call http://localhost:8090/v2/. Use localhost consistently rather than mixing it with 127.0.0.1. Browser requests must include credentials.

SameSite=Lax supports same-site deployments. Allowlisting an origin does not add cross-site iframe cookie login. Bearer-token integrations remain available.

Bootstrap a tenant administrator​

The existing deployment administrator credential, Authorization: Bearer admin:<configured adminPassword>, can provision the first tenant administrator. Use it from a trusted administration client. Deployment administrators may specify tenantId; ordinary tenant administrators can manage only their own tenant.

  1. Read and configure auth/policy, explicitly enabling the desired email method and setting permissions that contain $hkt_realm.
  2. Create the administrator's profile with POST service/people/, including their email.
  3. Use the returned person ID with PUT service/people/{personId}/access, setting enabled: true, isTenantAdmin: true, the required application permissions and allowedMethods.
  4. Send POST service/people/{personId}/invite with that person's email, then complete the login/setup flow.

See the People & Roles API for complete payloads. Once provisioned, the server prevents demoting, disabling or archiving the last active administrator with platform access. Keep another active administrator before changing the first account.

Upgrade existing installations​

Back up the database before upgrading. Startup migrations run transactionally under a database-wide lock and preserve established person UUIDs, credentials and compatible existing sessions. Global migration version 13 introduces people and private authentication storage; version 14 unifies the person contact/login email. Applied migrations are skipped on later starts.

Existing session records become people and email identities. Conflicting normalized emails or multiple email identities for one person cause migration rollback with conflict details. Resolve those records before retrying; the server does not silently merge people or change historical IDs. Directory-only addresses are reserved with platform access disabled.

The first upgrade imports legacy authType, authEmailDomains and authSessionLifetime settings into database policy. Thereafter manage tenant login policy through the app or API; YAML domain settings do not overwrite it. Remove legacy authEmailDomains after successful migration. Existing broad OTP permission grants are preserved and should be reviewed before enabling signup; password login must be explicitly enabled.

Authentication tables, including sessions, credentials and challenges, are in the private auth schema. Operational records remain in public.people, public.roles and public.people_directory. Reporting/query roles must not access private authentication storage; runtime and migration database credentials remain privileged.

Downgrading the binary alone after these schema changes is unsupported. Restore the matching database backup when rolling back.

Existing SSO deployments​

Existing configured JWT, Google Identity Platform and Cognito integrations remain available. Configure provider bindings under Settings → People → Authentication to manage external identities and choose claim-based or local permissions. Keep signing keys and service-account configuration in deployment settings. No new OIDC/SAML redirect or LDAP integration is introduced.

See Authentication Settings for policy and provider behavior, and the Authentication API for session revocation and password endpoints.