View User Management API Reference

Overview

The View User management system provides comprehensive user lifecycle management within tenant boundaries. Users define individual accounts or service identities that have access to View and the data stored therein, enabling secure authentication, authorization, and access control across the platform.

Key Features

User Authentication: Secure user authentication with SHA-256 password hashing
Tenant Isolation: Users are strictly isolated within tenant boundaries for enhanced security
Profile Management: Complete user profile management including names, email, and notes
Active/Inactive States: Control user availability and access through active status
Protection Controls: Mark users as proteed to prevent accidental modification
Administrative Control: Full administrative access for user management
Credential Integration: Automatic credential management and cleanup
Security Features: Password hashing and secure credential storage

Supported Operations

Create: Create new user accounts with authentication credentials
Read: Retrieve individual user profiles and metadata
Enumerate: List all users with pagination support
Update: Modify existing user profiles and settings
Delete: Remove user accounts and associated credentials
Existence Check: Verify user presence without retrieving details

API Endpoints

Users are managed via the Configuration server API at [http|https]://[hostname]:[port]/v1.0/tenants/[tenant-guid]/users

Supported HTTP Methods: GET, HEAD, PUT, DELETE

Important: All user operations require administrator-level access tokens.

User Object Structure

User objects contain comprehensive profile and authentication information for individual accounts or service identities. Here's the complete structure:

{
    "GUID": "default",
    "TenantGUID": "default",
    "FirstName": "Default",
    "LastName": "User",
    "FullName": "Default User",
    "Notes": "Default password is password",
    "Email": "[email protected]",
    "PasswordSha256": "************************************************************42d8",
    "Active": true,
    "IsProtected": false,
    "CreatedUtc": "2024-07-10T05:09:31.000000Z"
}

Field Descriptions

GUID (GUID): Globally unique identifier for the user object
TenantGUID (GUID): Globally unique identifier for the tenant
FirstName (string): User's first name
LastName (string): User's last name
FullName (string): Derived string comprised of: FirstName + ' ' + LastName
Notes (string): Administrator-supplied notes about the user
Email (string): Email address for the user (used for authentication)
PasswordSha256 (string): SHA-256 hash of the user's password
Active (boolean): Indicates whether the user is considered active and able to be used
IsProtected (boolean): Indicates whether the user is protected from modification
CreatedUtc (datetime): UTC timestamp when the user was created

Security Notes

Password Security: The user's password is never stored by View, but rather the SHA-256 hash within the PasswordSha256 property
Password Redaction: The PasswordSha256 property is redacted when retrieving, enumerating, or updating the user object for security
Tenant Isolation: Users are strictly isolated within tenant boundaries for enhanced security
Administrative Access: All user operations require administrator-level authentication tokens

Create User

Creates a new user account using PUT /v1.0/tenants/[tenant-guid]/users. This endpoint allows you to create new user accounts with authentication credentials and profile information.

Request Parameters

Required Parameters

FirstName (string, Body, Required): User's first name
LastName (string, Body, Required): User's last name
Email (string, Body, Required): Email address for the user (used for authentication)
PasswordSha256 (string, Body, Required): SHA-256 hash of the user's password

Optional Parameters

Notes (string, Body, Optional): Administrator-supplied notes about the user

Important Notes

Password Hashing: The password must be provided as a SHA-256 hash, not the plain text password
Administrator Access: This operation requires administrator-level authentication tokens
Email Uniqueness: Email addresses should be unique within the tenant
Security: Never store or transmit plain text passwords

curl -X PUT http://localhost:8601/v1.0/tenants/[tenant-guid]/users \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer [accesskey]" \
     -d '
{
  "FirstName": "Test",
  "LastName": "User",
  "Email": "[email protected]",
  "PasswordSha256": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
}'

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

api.accessToken = "<adminToken>" //This API requires Admin access

export const createUser = async () => {
  try {
    const user = await api.User.create(({
      FirstName: "John",
      LastName: "Doe",
      Notes: "Default password is password",
      Email: "[email protected]",
      PasswordSha256:
        "*********",
    });
    console.log(user, "User created successfully");
  } catch (err) {
    console.log("Error creating User:", err);
  }
};

createUser();

import view_sdk
from view_sdk import configuration

ssdk = view_sdk.configure(
    access_key="default",
    base_url="localhost", 
    tenant_guid="default",
    service_ports={Service.DEFAULT: 8000},
)

def createUser():
    user = configuration.User.create(
        FirstName="New",
        LastName="User",
        Notes="Default password is password",
        Email="[email protected]",
        PasswordSha256="*********"
    )
    print(user)

createUser()

using View.Sdk;
using View.Sdk.Configuration;

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("<tenant-guid>"),"default", "http://localhost:8000/");

UserMaster request = new UserMaster
 {
  FirstName = "John",
  LastName = "Doe",
  Email = "[email protected]",
  Notes= "Default password is password",
  PasswordSha256= "*********",
};

UserMaster response = await sdk.User.Create(request);

Response

Returns the created user object with all profile details:

{
    "GUID": "default",
    "TenantGUID": "default",
    "FirstName": "John",
    "LastName": "Doe",
    "FullName": "John Doe",
    "Notes": "Default password is password",
    "Email": "[email protected]",
    "PasswordSha256": "************************************************************42d8",
    "Active": true,
    "IsProtected": false,
    "CreatedUtc": "2024-07-10T05:09:31.000000Z"
}

Enumerate Users

Retrieves a paginated list of all user objects in the tenant using GET /v2.0/tenants/[tenant-guid]/users. This endpoint provides comprehensive enumeration with pagination support for managing multiple user accounts.

Request Parameters

No additional parameters required beyond authentication.

curl --location 'http://view.homedns.org:8000/v2.0/tenants/00000000-0000-0000-0000-000000000000/users' \
--header 'Authorization: ••••••'

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

api.accessToken = "<adminToken>" //This API requires Admin access

export const enumerateUsers = async () => {
  try {
    const users = await api.User.enumerate();
    console.log(users, "Users fetched successfully");
  } catch (err) {
    console.log("Error fetching Users:", err);
  }
};

enumerateUsers();

import view_sdk
from view_sdk import configuration

sdk = view_sdk.configure(
    access_key="default",
    base_url="localhost", 
    tenant_guid="default",
    service_ports={Service.DEFAULT: 8000},
)

def enumerateUsers():
    users = configuration.User.enumerate()
    print(users)

enumerateUsers()

using View.Sdk;
using View.Sdk.Configuration;

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("<tenant-guid>"),"default", "http://localhost:8000/");
EnumerationResult<UserMaster> response = await sdk.User.Enumerate();

Response

Returns a paginated list of user objects:

{
    "Success": true,
    "Timestamp": {
        "Start": "2024-10-21T02:36:37.677751Z",
        "TotalMs": 23.58,
        "Messages": {}
    },
    "MaxResults": 10,
    "IterationsRequired": 1,
    "EndOfResults": true,
    "RecordsRemaining": 0,
    "Objects": [
        {
            "GUID": "default",
            "TenantGUID": "default",
            "FirstName": "Default",
            "LastName": "User",
            "FullName": "Default User",
            "Notes": "Default password is password",
            "Email": "[email protected]",
            "PasswordSha256": "************************************************************42d8",
            "Active": true,
            "IsProtected": false,
            "CreatedUtc": "2024-07-10T05:09:31.000000Z"
        }
    ],
    "ContinuationToken": null
}

Read User

Retrieves user profile and metadata by GUID using GET /v1.0/tenants/[tenant-guid]/users/[user-guid]. Returns the complete user profile including all properties and metadata. If the user doesn't exist, a 404 error is returned.

Request Parameters

user-guid (string, Path, Required): GUID of the user object to retrieve

{
    "GUID": "default",
    "TenantGUID": "default",
    "FirstName": "Default",
    "LastName": "User",
    "FullName": "Default User",
    "Notes": "Default password is password",
    "Email": "[email protected]",
    "PasswordSha256": "************************************************************42d8",
    "Active": true,
    "CreatedUtc": "2024-07-10T05:09:31.000000Z"
}

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: ••••••'

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

api.accessToken = "<adminToken>" //This API requires Admin access

export const getUser = async () => {
  try {
    const user = await api.User.read("<user-guid>");
    console.log(user, "User fetched successfully");
  } catch (err) {
    console.log("Error fetching User:", err);
  }
};

getUser();

import view_sdk
from view_sdk import configuration

sdk = view_sdk.configure(
    access_key="default",
    base_url="localhost", 
    tenant_guid="default",
    service_ports={Service.DEFAULT: 8000},
)

def readUser():
    user = configuration.User.retrieve("<user-guid>")
    print(user)

readUser()

using View.Sdk;
using View.Sdk.Configuration;

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("<tenant-guid>"),"default", "http://localhost:8000/");
            
UserMaster response = await sdk.User.Retrieve(Guid.Parse("<user-guid>"));

Response

Returns the complete user profile:

{
    "GUID": "default",
    "TenantGUID": "default",
    "FirstName": "Default",
    "LastName": "User",
    "FullName": "Default User",
    "Notes": "Default password is password",
    "Email": "[email protected]",
    "PasswordSha256": "************************************************************42d8",
    "Active": true,
    "IsProtected": false,
    "CreatedUtc": "2024-07-10T05:09:31.000000Z"
}

Note: the HEAD method can be used as an alternative to get to simply check the existence of the object. HEAD requests return either a 200/OK in the event the object exists, or a 404/Not Found if not. No response body is returned with a HEAD request.

Read All Users

Retrieves all user objects in the tenant using GET /v1.0/tenants/[tenant-guid]/users/. Returns an array of user objects with complete profile details for all users in the tenant.

Request Parameters

No additional parameters required beyond authentication.

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/users' \
--header 'Authorization: ••••••'

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

api.accessToken = "<adminToken>" //This API requires Admin access


export const getUsers = async () => {
  try {
    const users = await api.User.readAll();
    console.log(users, "Users fetched successfully");
  } catch (err) {
    console.log("Error fetching Users:", err);
  }
};

getUsers();

import view_sdk
from view_sdk import configuration

sdk = view_sdk.configure(
    access_key="default",
    base_url="localhost", 
    tenant_guid="default",
    service_ports={Service.DEFAULT: 8000},
)

def readAllUsers():
    users = configuration.User.retrieve_all()
    print(users)

readAllUsers()

using View.Sdk;
using View.Sdk.Configuration;

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("<tenant-guid>"),"default", "http://localhost:8000/");
            
List<UserMaster> response = await sdk.User.RetrieveMany();

Response

Returns an array of all user objects:

[
    {
        "GUID": "default",
        "TenantGUID": "default",
        "FirstName": "Default",
        "LastName": "User",
        "FullName": "Default User",
        "Notes": "Default password is password",
        "Email": "[email protected]",
        "PasswordSha256": "************************************************************42d8",
        "Active": true,
        "IsProtected": false,
        "CreatedUtc": "2024-07-10T05:09:31.000000Z"
    },
    {
        "GUID": "b9a4e282-7add-4951-8654-d61ad49f6130",
        "TenantGUID": "default",
        "FirstName": "Jane",
        "LastName": "Smith",
        "FullName": "Jane Smith",
        "Notes": "Administrator user",
        "Email": "[email protected]",
        "PasswordSha256": "************************************************************abcd",
        "Active": true,
        "IsProtected": true,
        "CreatedUtc": "2024-07-11T10:15:30.123456Z"
    }
]

Update User

Updates an existing user profile using PUT /v1.0/tenants/[tenant-guid]/users/[user-guid]. This endpoint allows you to modify user profile parameters while preserving certain immutable fields.

Request Parameters

user-guid (string, Path, Required): GUID of the user object to update

Updateable Fields

All profile parameters can be updated except for:

GUID: Immutable identifier
TenantGUID: Immutable tenant association
CreatedUtc: Immutable creation timestamp

Important Notes

Field Preservation: Certain fields cannot be modified and will be preserved across updates
Complete Object: Provide a fully populated object in the request body
Password Security: Password updates require SHA-256 hashed values
Validation: All updated parameters will be validated before applying changes

Request body:

{
    "FirstName": "Updated",
    "LastName": "User",
    "Notes": "Default password is password",
    "Email": "[email protected]",
    "PasswordSha256": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
}

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

api.accessToken = "<adminToken>" //This API requires Admin access

export const updateUser = async () => {
  try {
    const user = await api.User.update({
      GUID: "<user-guid>",
			TenantGUID: "<tenant-guid>,
      Active: true,
      IsProtected: false,
      FirstName: "New",
      LastName: "User",
      Notes: "Default password is password",
      Email: "[email protected]",
      PasswordSha256:
        "*************",
    });
    console.log(user, "User updated successfully");
  } catch (err) {
    console.log("Error updating User:", err);
  }
};

updateUser();

import view_sdk
from view_sdk import configuration

sdk = view_sdk.configure(
    access_key="default",
    base_url="localhost", 
    tenant_guid="default",
    service_ports={Service.DEFAULT: 8000},
)

def updateUser():
    user = configuration.User.update("<user-guid>",
        FirstName="New [updated]",
        LastName="User",
        Notes="Default password is password",
        Email="[email protected]",
        PasswordSha256="*************")
    print(user)

updateUser()

using View.Sdk;
using View.Sdk.Configuration;

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("<tenant-guid>"),"default", "http://localhost:8000/");
            
var request = new UserMaster
{
  GUID = Guid.Parse("<user-guid>"),
  FirstName = "Jack",
  LastName = "Donald",
  Email = "[email protected]",
  Notes = "Default password is password",
  PasswordSha256 = "*************",
};

UserMaster response = await sdk.User.Update(request);

Response

Returns the updated user object with all profile details:

{
    "GUID": "b9a4e282-7add-4951-8654-d61ad49f6130",
    "TenantGUID": "default",
    "FirstName": "Jack",
    "LastName": "Donald",
    "FullName": "Jack Donald",
    "Notes": "Default password is password",
    "Email": "[email protected]",
    "PasswordSha256": "************************************************************abcd",
    "Active": true,
    "IsProtected": false,
    "CreatedUtc": "2024-10-21T14:08:41.281865Z"
}

Delete User

Deletes a user object by GUID using DELETE /v1.0/tenants/[tenant-guid]/users/[user-guid]. This operation permanently removes the user account and all associated data from the system. Use with caution as this action cannot be undone.

Important Note: Deletion of a user triggers automatic deletion of associated credential objects.

Request Parameters

user-guid (string, Path, Required): GUID of the user object to delete

curl --location --request DELETE 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: ••••••' \

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

api.accessToken = "<adminToken>" //This API requires Admin access


export const deleteUser = async () => {
  try {
    const response = await api.User.delete(
      "<user-guid>"
    );
    console.log(response, "User deleted successfully");
  } catch (err) {
    console.log("Error deleting User:", err);
  }
};

deleteUser();

import view_sdk
from view_sdk import configuration

sdk = view_sdk.configure(
    access_key="default",
    base_url="localhost", 
    tenant_guid="default",
    service_ports={Service.DEFAULT: 8000},
)

def deleteUser():
    user = configuration.User.delete("<user-guid>")    
    print(user)

deleteUser()

using View.Sdk;
using View.Sdk.Configuration;

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("<tenant-guid>"),"default", "http://localhost:8000/");
            
bool deleted = await sdk.User.Delete(Guid.Parse("<user-guid>"));

Response

Returns 204 No Content on successful deletion. No response body is returned.

Check User Existence

Verifies if a user object exists without retrieving its profile using HEAD /v1.0/tenants/[tenant-guid]/users/[user-guid]. This is an efficient way to check user presence before performing operations.

Request Parameters

user-guid (string, Path, Required): GUID of the user object to check

curl --location --head 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: ••••••'

import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

api.accessToken = "<adminToken>" //This API requires Admin access


export const userExists = async () => {
  try {
    const response = await api.User.exists(
      "<user-guid>"
    );
    console.log(response, "User exists");
  } catch (err) {
    console.log("Error fetching User:", err);
  }
};

userExists();

import view_sdk
from view_sdk import configuration

sdk = view_sdk.configure(
    access_key="default",
    base_url="localhost", 
    tenant_guid="default",
    service_ports={Service.DEFAULT: 8000},
)

def existsUser():
    user = configuration.User.exists("<user-guid>")
    print(user)

existsUser()

using View.Sdk;
using View.Sdk.Configuration;

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("<tenant-guid>"),"default", "http://localhost:8000/");
        
bool exists = await sdk.User.Exists(Guid.Parse("<user-guid>"));

Response

200 No Content: User exists
404 Not Found: User does not exist
No response body: Only HTTP status code is returned

Note: HEAD requests do not return a response body, only the HTTP status code indicating whether the user exists.

Best Practices

When managing users in the View platform, consider the following recommendations for optimal user lifecycle management:

Password Security: Always use SHA-256 hashing for passwords and never store or transmit plain text passwords
Administrator Access: Ensure all user operations use administrator-level authentication tokens
Email Uniqueness: Maintain unique email addresses within each tenant for proper user identification
Active Status Management: Use the Active flag to temporarily disable users without deletion
Protection Settings: Mark critical users as protected to prevent accidental modification

Next Steps

After successfully managing users, you can:

User Authentication: Implement user authentication flows using the created user accounts
Credential Management: Create and manage API credentials for users using the credentials API
Access Control: Implement role-based access control using user associations and permissions
User Administration: Build administrative interfaces for user management and monitoring
Integration: Integrate user management with other View platform services and authentication systems