Users
TrackVision Users are the individual accounts that let you authenticate into app and API. Each user can belong to a role with associated access policies and permissions.
The users Object
User collection stores individual account information for system authentication and authorization.
| Field Name | Type | Description |
|---|---|---|
id | uuid | Primary key. Unique identifier for the user (UUID format). |
first_name | string | First name of the user. |
last_name | string | Last name of the user. |
email | string | Email address of the user. Must be unique across all users. |
password | string | Hashed password of the user for authentication. |
location | string | Optional location information for the user. |
title | string | Job title or role description for the user. |
description | string | Optional detailed description of the user. |
tags | object | Array of tags associated with the user for categorization. |
avatar | uuid | Foreign key to files collection for user avatar image. |
language | string | Language code for TrackVision UI (e.g., en-US, es-ES). |
appearance | string | UI appearance preference: auto, light, or dark. |
theme_light | string | Theme identifier to use in light mode. |
theme_dark | string | Theme identifier to use in dark mode. |
theme_light_overrides | object | Custom theme overrides for light mode. |
theme_dark_overrides | object | Custom theme overrides for dark mode. |
tfa_secret | string | Two-factor authentication secret key when TFA is enabled. |
status | string | User status: draft, invited, active, suspended, or archived. |
role | object | Foreign key to roles collection defining user permissions. |
token | string | Static access token for API authentication. |
policies | array of objects | Direct policy assignments through junction table. |
last_access | datetime | Timestamp of user's last API or system access. |
last_page | string | Last page accessed in the TrackVision application. |
provider | string | Authentication provider used (local, oauth, etc.). |
external_identifier | string | User ID from external authentication provider. |
auth_data | object | Additional authentication data from external providers. |
email_notifications | boolean | Whether user receives email notifications (default: true). |
List Users
List all users that exist in TrackVision.
Request
- REST
- GraphQL
POST /graphql/system
type Query {
users: [trackvision_users]
}
Query Parameters
Supports all global query parameters.
Response
An array of up to limit user objects. If no items are available, data will be an empty array.
Example
- REST
- GraphQL
GET /users
SEARCH /users
query {
users {
first_name
last_name
email
}
}
Retrieve a User
List an existing user by primary key.
Request
- REST
- GraphQL
GET /users/:id
POST /graphql/system
type Query {
users_by_id(id: ID!): trackvision_users
}
Query Parameters
Supports all global query parameters.
Response
Returns the requested user object.
Example
- REST
- GraphQL
GET /users/72a1ce24-4748-47de-a05f-ce9af3033727
POST /graphql/system
query {
users_by_id(id: "72a1ce24-4748-47de-a05f-ce9af3033727") {
first_name
last_name
email
}
}
Retrieve the Current User
Retrieve the currently authenticated user.
Request
- REST
- GraphQL
GET /users/me
POST /graphql/system
type Query {
users_me: trackvision_users
}
Query Parameters
Supports all global query parameters.
Response
Returns the user object for the currently authenticated user.
Example
- REST
- GraphQL
GET /users/me
query {
users_me {
email
}
}
Update the Current User
Update the authenticated user.
Request
- REST
- GraphQL
PATCH /users/me
Provide a partial user object as the body of your request.
POST /graphql/system
type Mutation {
update_users_me(data: update_trackvision_users_input!): trackvision_users
}
Query Parameters
Supports all global query parameters.
Response
Returns the updated user object for the authenticated user.
Example
- REST
- GraphQL
PATCH /users/me
{
"email": "new.email@example.com"
}
POST /graphql/system
mutation {
update_users_me(data: { email: "new.email@example.com" }) {
email
}
}
Create a User
Create a new user
Request
- REST
- GraphQL
POST /users
Provide a user object as the body of your request.
POST /graphql/system
type Mutation {
create_users_item(data: create_trackvision_users_input!): trackvision_users
}
Query Parameters
Supports all global query parameters.
Request Body
A partial user object.
email and password are required to authenticate with the default authentication provider.
Response
Returns the user object for the created user.
Example
- REST
- GraphQL
POST /users
{
"email": "another@example.com",
"password": "tr4ckvision",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}
POST /graphql/system
mutation {
create_users_item(
data: {
email: "another@example.com"
password: "tr4ckvision"
role: { id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", name: "Public", admin_access: false, enforce_tfa: false }
}
) {
email
role
}
}
Please note that if you include the Role in the create_users_items call it will be treated as an Upsert and not only
as adding a relationship. So make sure the ID exists, and the other parameters match the existing role, otherwise it
could be modified by the user call.
Create Multiple Users
Create multiple new users
Request
- REST
- GraphQL
POST /users
Provide an array of user objects as the body of your request.
POST /graphql/system
type Mutation {
create_users_items(data: [create_trackvision_users_input!]!): [trackvision_users]
}
Query Parameters
Supports all global query parameters.
Request Body
An array of partial user objects.
email and password are required.
Response
Returns the user objects for the created users.
Example
- REST
- GraphQL
POST /users
[
{
"email": "admin@example.com",
"password": "p455w0rd",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
},
{
"email": "another@example.com",
"password": "tr4ckvision",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}
]
POST /graphql/system
mutation {
create_users_items(
data: [
{
email: "admin@example.com"
password: "p455w0rd"
role: { id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", name: "Public", admin_access: false, enforce_tfa: false }
}
{
email: "another@example.com"
password: "tr4ckvision"
role: { id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", name: "Public", admin_access: false, enforce_tfa: false }
}
]
) {
email
role
}
}
Please note that if you include the Role in the create_users_items call it will be treated as an Upsert and not only
as adding a relationship. So make sure the ID exists, and the other parameters match the existing role, otherwise it
could be modified by the user call.
Update a User
Update an existing user.
Request
- REST
- GraphQL
PATCH /users/:id
Provide a partial user object as the body of your request.
POST /graphql/system
type Mutation {
update_users_item(id: ID!, data: update_trackvision_users_input!): trackvision_users
}
Query Parameters
Supports all global query parameters.
Request Body
A partial user object.
Response
Returns the user object for the updated user.
Example
- REST
- GraphQL
PATCH /users/72a1ce24-4748-47de-a05f-ce9af3033727
{
"title": "CTO"
}
POST /graphql/system
mutation {
update_users_item(id: "72a1ce24-4748-47de-a05f-ce9af3033727", data: { title: "CTO" }) {
first_name
last_name
}
}
Update Multiple Users
Update multiple existing users.
Request
- REST
- GraphQL
PATCH /users
{
"keys": user_id_array,
"data": partial_user_object
}
POST /graphql/system
type Mutation {
update_users_items(ids: [ID!]!, data: update_trackvision_users_input!): [trackvision_users]
}
Query Parameters
Supports all global query parameters.
Request Body
keys Required
Array of primary keys of the users you'd like to update.
data Required
Any of the user object's properties.
Response
Returns the user objects for the updated users.
Example
- REST
- GraphQL
PATCH /users
{
"keys": ["72a1ce24-4748-47de-a05f-ce9af3033727", "9c3d75a8-7a5f-41a4-be0a-1488fd974511"],
"data": {
"title": "CTO"
}
}
POST /graphql/system
mutation {
update_users_items(
ids: ["72a1ce24-4748-47de-a05f-ce9af3033727", "9c3d75a8-7a5f-41a4-be0a-1488fd974511"]
data: { title: "CTO" }
) {
first_name
last_name
}
}
Delete a User
Delete an existing user.
Request
- REST
- GraphQL
DELETE /users/:id
POST /graphql/system
type Mutation {
delete_users_item(id: ID!): delete_one
}
Response
Empty body.
Example
- REST
- GraphQL
DELETE /users/72a1ce24-4748-47de-a05f-ce9af3033727
POST /graphql/system
mutation {
delete_users_item(id: "72a1ce24-4748-47de-a05f-ce9af3033727") {
id
}
}
Delete Multiple Users
Delete multiple existing users.
Request
- REST
- GraphQL
DELETE /users
Provide an array of user IDs as the body of your request.
POST /graphql/system
type Mutation {
delete_users_items(ids: [ID!]!): delete_many
}
Request Body
An array of user primary keys
Response
Empty body.
Example
- REST
- GraphQL
DELETE /users
["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]
POST /graphql/system
mutation {
delete_users_items(ids: ["72a1ce24-4748-47de-a05f-ce9af3033727", "9c3d75a8-7a5f-41a4-be0a-1488fd974511"]) {
ids
}
}
Register a new User
Register a new user.
Request
- REST
- GraphQL
POST /users/register
{
"email": user_email,
"password": user_password
}
POST /graphql/system
type Mutation {
users_register(email: String!, password: String!): True
}
Note: This mutation always returns true.
Request Body
email Required
Email for the new user.
password Required
Password for the new user.
first_name
First name for the new user.
last_name
Last name for the new user.
verification_url
Provide a custom verification url which the link in the email will lead to. The verification token will be passed as a parameter.
Note: You need to configure the
USER_REGISTER_URL_ALLOW_LIST environment variable to enable this feature.
Response
Empty body.
Example
- REST
- GraphQL
POST /users/register
{
"email": "another@example.com",
"password": "d1r3ctus"
}
POST /graphql/system
mutation {
users_register(email: "another@example.com", password: "tr4ckvision")
}
Note: This mutation always returns true.
Verify Registered Email
Verify the registered email address. The register user endpoint sends the email a link for verification.
This link includes a token, which is then used to activate the registered user.
Request
- REST
- GraphQL
GET /users/register/verify-email?token=token
POST /graphql/system
type Mutation {
users_register_verify(token: String!): True
}
Note: This mutation always returns true.
Query Parameters
token Required
Emailed registration token.
Response
Empty body.
Example
- REST
- GraphQL
GET /users/register/verify-email?token=eyJh...KmUk
mutation {
users_register_verify(token: "eyJh...KmUk")
}
Note: This mutation always returns true.
Invite a new User
Invite a new user by email.
Request
- REST
- GraphQL
POST /users/invite
{
"email": invited_user_email,
"role": invited_user_role
}
POST /graphql/system
type Mutation {
users_invite(email: String!, role: String!, invite_url: String): Boolean
}
Request Body
email Required
User email to invite.
role Required
Role of the new user.
invite_url
Provide a custom invite url which the link in the email will lead to. The invite token will be passed as a parameter.
Note: You need to configure the USER_INVITE_URL_ALLOW_LIST environment variable to enable this feature.
Response
Empty body.
Example
- REST
- GraphQL
POST /users/invite
{
"email": "another@example.com",
"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"
}
POST /graphql/system
mutation {
users_invite(email: "another@example.com", role: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7")
}
Accept User Invite
Accept your invite. The invite user endpoint sends the email a link to the TrackVision UI.
This link includes a token, which is then used to activate the invited user.
Request
- REST
- GraphQL
POST /users/invite/accept
{
"token": invite_token,
"password": user_password
}
POST /graphql/system
type Mutation {
users_invite_accept(token: String!, password: String!): Boolean
}
Request Body
token Required
Accept invite token.
password Required
Password for the user.
Response
Empty body.
Example
- REST
- GraphQL
POST /users/invite/accept
{
"token": "eyJh...KmUk",
"password": "tr4ckvision"
}
mutation {
users_invite_accept(token: "eyJh...KmUk", password: "tr4ckvision")
}
Generate Two-Factor Authentication Secret
Generates a secret and returns the URL to be used in an authenticator app.
Request
- REST
- GraphQL
POST /users/me/tfa/generate
{
"password": user_password
}
POST /graphql/system
type Mutation {
users_me_tfa_generate(password: String!): users_me_tfa_generate_data
}
Request Body
password Required
The user's password.
Response
secret string
OTP secret to be saved in the authenticator app.
otpauth_url string
otpauth:// formatted URL. Can be rendered as QR code and used in most authenticator apps.
Example
- REST
- GraphQL
POST /users/me/tfa/generate
{
"password": "tr4ckvision"
}
POST /graphql/system
mutation {
users_me_tfa_generate(password: "tr4ckvision") {
secret
otpauth_url
}
}
Enable Two-Factor Authentication
Adds a TFA secret to the user account.
Request
- REST
- GraphQL
POST /users/me/tfa/enable
{
"otp": one_time_password,
"secret": two_factor_authorization_secret
}
POST /graphql/system
type Mutation {
users_me_tfa_enable(otp: String!, secret: String!): Boolean
}
Request Body
secret Required
The TFA secret from tfa/generate.
otp Required
OTP generated with the secret, to recheck if the user has a correct TFA setup
Response
Empty response.
Example
- REST
- GraphQL
POST /users/me/tfa/enable
{
"otp": "123456",
"secret": "3CtiutsNBmY3szHE"
}
POST /graphql/system
mutation {
users_me_tfa_enable(otp: "123456", secret: "3CtiutsNBmY3szHE")
}
Disable Two-Factor Authentication
Disables two-factor authentication by removing the OTP secret from the user.
Request
- REST
- GraphQL
POST /users/me/tfa/disable
{
"otp": one_time_password
}
POST /graphql/system
type Mutation {
users_me_tfa_disable(otp: String!): Boolean
}
Request Body
otp Required
One-time password generated by the authenticator app.
Response
Empty response.
Example
- REST
- GraphQL
POST /users/me/tfa/disable
{
"otp": "859014"
}
POST /graphql/system
mutation {
users_me_tfa_disable(otp: "591763")
}