Users API

User-scoped writes that must be validated server-side. A logged-in user has no direct GraphQL write access to showrooms or business profiles; every create/update goes through this API, which authenticates the user's access token and validates ownership before mutating (using the Hasura admin secret). Powers the first-login onboarding flow: creating a project (showroom), setting its locale/timezone, and managing business profiles.

Server

URL	Description
https://api.neogt.com.au/users	Production

projectCodeAvailability

GET /projects/code-availability

Check whether a project code is valid and not already taken. The code is a URL-safe slug and is a UNIQUE column on showrooms.

Parameters

Name	In	Type	Required	Description
code	query	string	yes	The desired project code, e.g. "acme-motors"

Responses

Status	Description
200	Availability result
401	Authentication is missing or invalid

listProjects

GET /projects

List the projects (showrooms) the caller belongs to.

Responses

Status	Description
200	The caller's projects
401	Authentication is missing or invalid

createProject

POST /projects

Create a project (showroom) and make the caller its owner. Validates the code format and uniqueness.

Request body

Field	Type	Required	Description
name	string	yes	Human-friendly project name Example: "Acme Motors".
code	string	yes	URL-safe unique slug Example: "acme-motors".
default_language	string	no	Default language. Example: "en-GB".

Responses

Status	Description
201	Project created
400	The request is invalid
401	Authentication is missing or invalid
409	The code is already taken

updateProject

PATCH /projects/{code}

Update locale/region/timezone for a project the caller owns.

Parameters

Name	In	Type	Required	Description
code	path	string	yes

Request body

Field	Type	Required	Description
default_language	string	no	Example: "en".
default_region	string	no	Example: "AU_SYD".
timezone	string	no	Example: "Australia/Sydney".

Responses

Status	Description
200	Project updated
400	The request is invalid
401	Authentication is missing or invalid
403	The caller may not manage this project
404	The record was not found

listBusinessProfiles

GET /business-profiles

List the caller's business profiles.

Responses

Status	Description
200	The caller's business profiles
401	Authentication is missing or invalid

createBusinessProfile

POST /business-profiles

Create a business profile owned by the caller.

Request body

Field	Type	Required	Description
name	string	yes	Example: "Acme Motors Ltd".
relationship	string	no
registration_number	string	no
address	Address	no	Free-form structured address (stored as JSONB).
phone	string	no
email	string	no

Responses

Status	Description
201	Business profile created
400	The request is invalid
401	Authentication is missing or invalid

requestContactChange

POST /contact-change

Start changing the caller's email address or phone number. The value is validated and normalized (emails lowercased; phones to +<country><number>), rejected if another account holds it, and a short-lived confirmation code is sent to the NEW address or number. Nothing changes on the user until /contact-change/confirm succeeds.

Request body

Field	Type	Required	Description
type	string	yes
value	string	yes	Example: "new@example.com".

Responses

Status	Description
201	Confirmation code sent
400	The request is invalid
401	Authentication is missing or invalid
409	The value is held by another account. code is err_contact_taken, or err_contact_taken_recoverable when the holder is a soft-deleted account (the UI should point the user at account recovery).

confirmContactChange

POST /contact-change/confirm

Confirm a pending email/phone change with the code that was sent to the new address or number. Applies the change to the caller's user on success. Requests are single-use, expire after a few minutes and lock after too many wrong tries.

Request body

Field	Type	Required	Description
request_id	string	yes
code	string	yes	Example: "123456".

Responses

Status	Description
200	Contact detail updated
400	The request is invalid
401	Authentication is missing or invalid
404	The record was not found
409	The value was claimed by another account in the meantime
410	The code has expired

listTeam

GET /team

The team: one membership row per (showroom × user) across every showroom the caller owns, plus the list of owned showrooms for the invite form's picker.

Responses

Status	Description
200	Team members and owned showrooms
401	Authentication is missing or invalid

getAccessCatalog

GET /access-catalog

The grant + access catalogs used to build a role's permissions.

Responses

Status	Description
200	Grant and access catalogs
401	Authentication is missing or invalid

archiveShowroomSite

POST /showrooms/{code}/archive

Archive a showroom site. Owners only.

Parameters

Name	In	Type	Required	Description
code	path	string	yes

Responses

Status	Description
200	Showroom archived
401	Authentication is missing or invalid
403	The caller may not manage this project
404	The record was not found

unarchiveShowroomSite

POST /showrooms/{code}/unarchive

Restore an archived showroom site. Owners only.

Parameters

Name	In	Type	Required	Description
code	path	string	yes

Responses

Status	Description
200	Showroom restored
401	Authentication is missing or invalid
403	The caller may not manage this project
404	The record was not found

requestShowroomSiteDelete

POST /showrooms/{code}/delete-requests

Queue a later hard delete for an archived showroom. Owners only.

Parameters

Name	In	Type	Required	Description
code	path	string	yes

Responses

Status	Description
202	Delete request queued
400	The request is invalid
401	Authentication is missing or invalid
403	The caller may not manage this project
404	The record was not found

listShowroomRoles

GET /showrooms/{code}/roles

List the roles defined for a showroom the caller owns.

Parameters

Name	In	Type	Required	Description
code	path	string	yes

Responses

Status	Description
200	The showroom's roles
401	Authentication is missing or invalid
403	The caller may not manage this project

createShowroomRole

POST /showrooms/{code}/roles

Create a role for a showroom the caller owns.

Parameters

Name	In	Type	Required	Description
code	path	string	yes

Request body

Field	Type	Required	Description
name	string	yes	Example: "Sales manager".
description	string	no
grants	array<GrantAccess>	no

Responses

Status	Description
201	Role created
400	The request is invalid
401	Authentication is missing or invalid
403	The caller may not manage this project

updateShowroomRole

PATCH /showrooms/{code}/roles/{roleId}

Rename a role and replace its grants.

Parameters

Name	In	Type	Required	Description
code	path	string	yes
roleId	path	string	yes

Request body

Field	Type	Required	Description
name	string	yes
description	string	no
grants	array<GrantAccess>	no

Responses

Status	Description
200	Role updated
400	The request is invalid
401	Authentication is missing or invalid
403	The caller may not manage this project
404	The record was not found

deleteShowroomRole

DELETE /showrooms/{code}/roles/{roleId}

Delete a role (its grants cascade).

Parameters

Name	In	Type	Required	Description
code	path	string	yes
roleId	path	string	yes

Responses

Status	Description
200	Role deleted
401	Authentication is missing or invalid
403	The caller may not manage this project
404	The record was not found

getShowroomAssignable

GET /showrooms/{code}/assignable

Locations and locales the owner can attach to a data-aware limited grant when assigning a role in a showroom they own.

Parameters

Name	In	Type	Required	Description
code	path	string	yes

Responses

Status	Description
200	Assignable locations and locales
401	Authentication is missing or invalid
403	The caller may not manage this project

updateMemberRoles

PATCH /showrooms/{code}/members/{userId}/roles

Replace a member's roles in a showroom the caller owns and re-materialise their grants, capturing the location/locale chosen for any data-aware limited grant.

Parameters

Name	In	Type	Required	Description
code	path	string	yes
userId	path	string	yes

Request body

Field	Type	Required	Description
role_ids	array<string>	yes
grant_assignments	array<GrantAssignment>	no

Responses

Status	Description
200	Roles updated
400	The request is invalid
401	Authentication is missing or invalid
403	The caller may not manage this project
404	The record was not found

getMemberPermissions

GET /showrooms/{code}/members/{userId}/permissions

A member's effective permissions in a showroom the caller owns.

Parameters

Name	In	Type	Required	Description
code	path	string	yes
userId	path	string	yes

Responses

Status	Description
200	The member's permissions
401	Authentication is missing or invalid
403	The caller may not manage this project

removeShowroomMember

DELETE /showrooms/{code}/members/{userId}

Remove a member from a showroom the caller owns.

Parameters

Name	In	Type	Required	Description
code	path	string	yes
userId	path	string	yes

Responses

Status	Description
200	Member removed
400	The request is invalid
401	Authentication is missing or invalid
403	The caller may not manage this project
404	The record was not found

createInvitation

POST /invitations

Invite someone to a showroom the caller owns by email or phone, pre-assigning showroom + roles. Creates/reuses a user, attaches a pending membership, and sends an accept/deny link.

Request body

Field	Type	Required	Description
showroom_code	string	yes
contact_type	string	yes
value	string	yes	Example: "new@example.com".
role_ids	array<string>	no
grant_assignments	array<GrantAssignment>	no
is_owner	boolean	no

Responses

Status	Description
201	Invitation created and link sent
400	The request is invalid
401	Authentication is missing or invalid
403	The caller may not manage this project

getInvitation

GET /invitations/{token}

Public summary of an invitation for the accept/deny page.

Parameters

Name	In	Type	Required	Description
token	path	string	yes

Responses

Status	Description
200	Invitation summary
404	The record was not found

acceptInvitation

POST /invitations/accept

Public — accept an invitation with its token.

Request body

Field	Type	Required	Description
token	string	yes
first_name	string	yes
last_name	string	yes

Responses

Status	Description
200	Invitation accepted
404	The record was not found
410	The invitation has expired or is no longer valid

denyInvitation

POST /invitations/deny

Public — decline an invitation with its token.

Request body

Field	Type	Required	Description
token	string	yes

Responses

Status	Description
200	Invitation declined
404	The record was not found
410	The invitation is no longer valid

listSystemUsers

GET /system-users

The system users the caller owns (machine accounts for collectors), each with its showroom membership, roles and whether an API client has been issued.

Responses

Status	Description
200	The caller's system users
401	Authentication is missing or invalid

createSystemUser

POST /system-users

Create a system user owned by the caller and give it an active membership (with roles + materialised grants) in a showroom the caller owns. Credentials are minted separately via the authentication-api.

Request body

Field	Type	Required	Description
name	string	yes
showroom_code	string	yes
role_ids	array<string>	no
grant_assignments	array<GrantAssignment>	no

Responses

Status	Description
201	System user created
400	The request is invalid
401	Authentication is missing or invalid
403	The caller may not manage this project

connectCollector

POST /system-users/connect-collector

One-click collector provisioning: in a showroom the caller owns, reuse or create a role granting only WRITE on devices, then create a system user with that role. Credentials are minted separately via the authentication-api.

Request body

Field	Type	Required	Description
showroom_code	string	yes

Responses

Status	Description
201	Collector provisioned
401	Authentication is missing or invalid
403	The caller may not manage this project

deleteSystemUser

DELETE /system-users/{userId}

Soft-delete a system user the caller owns.

Parameters

Name	In	Type	Required	Description
userId	path	string	yes

Responses

Status	Description
200	System user deleted
401	Authentication is missing or invalid
404	The record was not found