Authentication

Hivekit supports email-code login, local passwords and existing external JWT integrations. Paths below are relative to the configured REST root, usually /v2/. Send JSON with Content-Type: application/json.

Local browser login uses the HttpOnly, SameSite=Lax hkt_session cookie. Browser clients must use credentials: 'include' on login, confirmation, session and logout requests. After login, GET auth/session/ returns a JWT in data.token for authenticated API calls and SDK connections. This cookie contains a session secret, not a JWT; it is separate from the configurable authCookieName used by external-token integrations.

Successful operations return {"result":"success"}, with a data property when returning content. auth/config is a legacy exception that returns its configuration directly. Errors return {"result":"error","message":"..."} with an HTTP error status.

Discover login methods

POST auth/methods/ accepts:

{
  "email": "jane@example.com",
  "tenantId": "example-tenant"
}

tenantId is optional. When omitted, the server uses the configured email tenant-split rule or the default tenant. The response contains only permitted local methods and password availability:

{
  "result": "success",
  "data": {
    "methods": [
      "email_otp",
      "password"
    ],
    "hasPassword": true
  }
}

Methods must be allowed by both the tenant policy and email identity. Disabled accounts and archived people receive no methods. Unknown emails receive only email_otp, and only when self-signup and domain restrictions allow it. Discovery is rate limited and intentionally reveals permitted method information; it returns no names or person IDs. SSO continues through the existing external-token entry point.

Email-code login

Method	Path	Request / behavior
POST	auth/email/login/	{ "email": "jane@example.com" }, optional tenantId; emails a code and sets the pending browser cookie.
POST	auth/email/confirm/	{ "confirmationCode": "123456" } plus that cookie; confirms the code and rotates to an authenticated session.
GET	auth/session/	Reads the pending or authenticated cookie session. Only a confirmed session supplies a usable token.
POST	auth/session/logout	Send {} with the cookie; ends the session or pending challenge and clears the cookie.
GET	auth/config	Public compatibility configuration: auth type, login domains, enabled methods and self-signup setting; optional tenantId.

Code completion must use the browser that initiated login. For new addresses, successful verification creates a person only when email self-signup is allowed. Reserved directory-only identities cannot bypass disabled access.

Password login and recovery

Method	Path	Request / behavior
POST	auth/password/login/	{ "email": "jane@example.com", "password": "..." }, optional tenantId; sets an authenticated session cookie. Read auth/session/ next to obtain the JWT.
POST	auth/password/forgot/	{ "email": "jane@example.com" }, optional tenantId; generic success response, with a recovery email for eligible accounts.
POST	auth/password/challenge/	{ "challengeId": "...", "code": "..." }; validates a password link and returns data.email and data.purpose without consuming it.
POST	auth/password/resend/	Same link proof; sends a replacement for an expired, unused challenge. Consumed, revoked or disabled-account links cannot renew.
POST	auth/password/reset/	{ "challengeId": "...", "code": "...", "password": "...", "purpose": "password_reset" }; accepts recovery, invitation and setup links.
POST	auth/password/change/	Authenticated; { "currentPassword": "...", "password": "..." }; changes the current person's local password.

Passwords require at least 12 characters and at most 1,024 bytes. Passwords are stored using Argon2id. Initial password setup requires administrator provisioning; there is no password self-signup endpoint.

Email links carry auth, challengeId and code in the frontend URL fragment. The auth purpose is password_reset, invitation or password_setup. A custom frontend should read and remove that fragment, validate the proof with auth/password/challenge/, then submit the password to auth/password/reset/. If supplied, purpose must match the validated challenge. Users follow links rather than manually entering challenge IDs or secrets.

Successful password setup/reset consumes the challenge, revokes other outstanding challenges and local sessions, and clears the browser session cookie. Password changes also revoke local sessions. Sign in again after saving a password. Account email, identities and access settings require administrator access; users manage only their own password through these endpoints.

Current account

Authenticated calls use Authorization: Bearer TOKEN:

Method	Path	Response
GET	auth/me	data.person, current data.user principal and data.isTenantAdmin. The person may be absent for a legacy external principal.
GET	auth/me/identities	data array of the current person's email metadata: email, allowed_methods, enabled, has_password.

Credential hashes and challenge secrets are never returned by account metadata endpoints.

Session lifecycle and external tokens

Local JWTs include an explicit expiry and session reference. Validation checks the current session, person, identity and method policy. Logout, password changes/resets, access updates and established email changes invalidate local sessions. Managed persistent connections are rechecked on traffic and every five seconds while idle.

Existing configured JWT, Google Identity Platform and Cognito validators remain supported. Provider bindings opt issuers into managed identities, person IDs and access lifecycle. External authentication remains direct bearer authentication rather than an exchange for a local cookie session. The tenant's sso policy also governs unregistered external user-token login; machine/data-provider and local association/read-only tokens retain their existing paths.

Errors and browser deployment

Expect 400 for invalid input, 403 for denied authentication or administration, 409 for conflicting updates, and 429 for rate limits. Missing password-email frontend configuration returns 503; automatic password-setup delivery failure returns 502 and rolls back the access update.

Authentication requests enforce trusted browser origins independently of broad CORS settings. For separate frontend/API origins and TLS proxies, see deployment configuration. Same-site browser deployments are supported; cross-site iframe cookie login is not added by these endpoints.

For tenant administration, use the People & Roles API. For app workflows, see Signing in & Passwords.