People & Roles

People, roles, policies, providers and access settings belong to a tenant. All endpoints on this page require a managed tenant administrator or deployment administrator. Operational roles and realm permissions do not grant tenant-administrator access.

Paths are relative to the REST root, usually /v2/. Send JSON and Authorization: Bearer TOKEN. Tenant administrators can access only their own tenant. Deployment administrators can specify tenantId to select another tenant; otherwise they use the default tenant. See administrator bootstrap.

Responses use {"result":"success","data":...}. Person, role, identity and provider records use database snake_case keys; request bodies use camelCase. Creation responses include data.id. List reads return arrays, including a single-person read. Access reads return either data: [] or a one-element array with enabled, isTenantAdmin and permissions.

PUT requests replace the supplied resource rather than patching it. Read existing values and retain all profile, policy or access fields when updating. Access allowedMethods is optional; omit it to retain email methods, or supply an array to replace them.

People and roles

Method	Path	Behavior
GET	service/people/	Lists tenant people, including archived records.
GET	service/people/{personId}	Returns a person in a data array.
POST	service/people/	Creates a person; optional explicit UUID id, otherwise a random UUID.
PUT	service/people/{personId}	Replaces the profile; use status to archive/reactivate.
GET	service/roles/	Lists operational roles.
POST	service/roles/	Creates a role.
PUT	service/roles/{roleId}	Replaces its label and status.

Example person body:

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane@example.com",
  "role": null,
  "reportsTo": null,
  "objectId": null,
  "objectRealmId": null,
  "status": "active"
}

role and reportsTo are tenant-scoped UUID references. Reporting relationships reject self-links and cycles. Object links require an existing object in a tenant realm and both IDs; each object can have at most one linked person. Status is active or archived.

Each person has one shared contact/login email, normalized by trimming and lowercasing. Email addresses are unique per tenant, including directory-only people. Creation reserves the address but does not enable platform access or create password credentials. Changing an established login email revokes local sessions and challenges and clears email verification while preserving person and credential IDs. An established email identity cannot have its address cleared; disable access to block login.

Example role body:

{
  "label": "Operator",
  "status": "active"
}

Operational roles do not grant application permissions. Archiving a person blocks managed authentication; archiving a role does not suspend its people's access.

Access and invitations

Method	Path	Behavior
GET	service/people/{personId}/access	Reads provisioned access in a list envelope.
PUT	service/people/{personId}/access	Replaces access; optional email methods use the saved profile email.
GET	service/people/{personId}/auth	Lists identity metadata, including email allowed_methods and has_password.
PUT	service/people/{personId}/auth/email	Compatibility endpoint for shared email and email identity settings.
POST	service/people/{personId}/invite	{ "email": "jane@example.com" }; address must belong to this person with enabled access.

Example access body:

{
  "enabled": true,
  "isTenantAdmin": false,
  "permissions": {
    "$hkt_realm": "",
    "mine-west": {
      "*": "R"
    }
  },
  "allowedMethods": [
    "email_otp",
    "password"
  ]
}

Include $hkt_realm explicitly in permissions. Email methods require a saved email and must also be enabled in the tenant policy. Saving access revokes existing local sessions.

For an already enabled email-code user without a password, granting password sign-in sends a setup email before committing the access change. SMTP failure rolls back the update; success includes data.passwordSetupSent. Initial provisioning still requires Send invitation. Invitations send a password setup link when password is permitted, or the ordinary login URL for code-only access.

The compatibility email endpoint accepts:

{
  "email": "jane@example.com",
  "enabled": true,
  "allowedMethods": [
    "email_otp",
    "password"
  ]
}

It also updates the person's shared email and never transfers an address from another person. Identity enablement does not replace the separate platform access flag.

Once a tenant has an active administrator with platform access, updates cannot remove the last one. Demoting, disabling or archiving that administrator returns 409. Administrators in another tenant, disabled administrators and archived administrators do not count. Assign a second active administrator first.

Login policy

GET auth/policy reads policy; PUT auth/policy replaces it:

{
  "enabledMethods": [
    "email_otp",
    "password",
    "sso"
  ],
  "emailSelfSignupEnabled": false,
  "emailSignupAllowedDomains": [
    "example.com"
  ],
  "emailLoginAllowedDomains": null,
  "defaultPermissions": {
    "$hkt_realm": ""
  },
  "sessionLifetimeSeconds": 86400,
  "challengeLifetimeSeconds": 600,
  "challengeMaxAttempts": 5
}

emailLoginAllowedDomains: null allows all domains for existing email identities; [] permits none; a populated array allows only those domains. Signup additionally requires self-signup to be enabled and an explicitly allowed signup domain. There is no password self-signup endpoint.

defaultPermissions must contain $hkt_realm. Valid limits are 60–31,536,000 seconds for sessions, 60–3,600 seconds for challenges and 1–20 verification attempts. These example values are configurable, not fixed defaults.

SSO providers and identities

GET auth/providers/, POST auth/providers/ and PUT auth/providers/{providerId} manage existing validator bindings:

{
  "name": "Company SSO",
  "type": "configured_jwt",
  "issuer": "enterprise-idp",
  "audiences": [
    "hivekit"
  ],
  "enabled": true,
  "autoProvisionPeople": false,
  "permissionsSource": "claims"
}

Types are configured_jwt, google and cognito. permissionsSource is claims or local; permissions are not automatically combined. Signing keys and validator credentials remain deployment configuration. Provider management does not implement browser redirects, SAML or LDAP.

With automatic provisioning off, link a stable provider subject using PUT service/people/{personId}/auth/external:

{
  "providerId": "00000000-0000-4000-8000-000000000001",
  "subject": "stable-provider-subject",
  "enabled": true
}

Replace the example UUID with the provider's returned ID. With automatic provisioning on, a first accepted token creates an independent person; email equality never automatically merges accounts. Managed external identities resolve to the stored person UUID and obey person/access, identity, provider and tenant SSO policy. Authentication continues using the provider's bearer token.

See the Authentication API for sign-in, sessions and password links, or People & Roles for the app workflow.