API Reference

Users

This page covers configuration and management of View user objects.

Object Overview

Users define individual or services that have access to View and the data stored therein.

Endpoint, URL, and Supported Methods

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

Supported methods include: GET HEAD PUT DELETE

Structure

Objects have the following 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"
}

Properties:

  • GUID GUID globally unique identifier for the object
  • TenantGUID GUID globally unique identifier for the tenant
  • FirstName string user first name
  • LastName string user last name
  • FullName string derived string comprised of: first + ' ' + last
  • Notes string administrator-supplied notes
  • Email string email address for the user
  • PasswordSha256 string the SHA-256 hash of the user's password
  • Active bool indicates whether or not the user is considered active and able to be used
  • IsProtected boole indicates whether or not the user is considered protected or not
  • CreatedUtc datetime timestamp from creation, in UTC time

Important: the user's password is never stored by View, but rather the SHA-256 hash within the PasswordSha256 property. As such this property is redacted when retrieving, enumerating, or updating the user object.

Create

To create, call PUT /v1.0/tenants/[tenant-guid]/users with the following properties using the configuration server: FirstName LastName Email PasswordSha256

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(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

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

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

createUser();

Enumerate

Refer to the Enumeration page in REST API for details about the use of enumeration APIs.

Enumerate objects by using GET /v2.0/tenants/[tenant-guid]/users. The resultant object will appear as:

{
    "Success": true,
    "Timestamp": {
        "Start": "2024-10-21T02:36:37.677751Z",
        "TotalMs": 23.58,
        "Messages": {}
    },
    "MaxResults": 10,
    "IterationsRequired": 1,
    "EndOfResults": true,
    "RecordsRemaining": 16,
    "Objects": [
        {
            "GUID": "example-user",
            ... user details ...
        },
        { ... }
    ],
    "ContinuationToken": "[continuation-token]"
}

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(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

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

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

enumerateUsers();

Read

To read an object by GUID, call GET /v1.0/tenants/[tenant-guid]/users/[user-guid]. If the object exists, it will be returned as a JSON object in the response body. If it does not exist, a 404 will be returned with a NotFound error response.

{
    "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(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

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

export const getUser = async () => {
  try {
    const user = await api.retrieveUser("0a54349a-39d4-4756-960d-9d7b6af9435c");
    console.log(user, "User fetched successfully");
  } catch (err) {
    console.log("Error fetching User:", err);
  }
};

getUser();

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

To read all object , call GET /v1.0/tenants/[tenant-guid]/users/. If the object exists, it will be returned as a array JSON object in the response body.

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(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

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


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

getUsers();

Update

To update an object by GUID, call PUT /v1.0/tenants/[tenant-guid]/users/[user-guid] with a fully populated object in the request body. The updated object will be returned to you.

Note: certain fields cannot be modified and will be preserved across updates.

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(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

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

export const updateUser = async () => {
  try {
    const user = await api.updateUser("0a54349a-39d4-4756-960d-9d7b6af9435c", {
      FirstName: "New",
      LastName: "User",
      Notes: "Default password is password",
      Email: "[email protected]",
      PasswordSha256:
        "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
    });
    console.log(user, "User updated successfully");
  } catch (err) {
    console.log("Error updating User:", err);
  }
};

updateUser();

Response body:

{
    "GUID": "b9a4e282-7add-4951-8654-d61ad49f6130",
    "TenantGUID": "default",
    "FirstName": "Updated",
    "LastName": "User",
    "FullName": "New User",
    "Notes": "Default password is password",
    "Email": "[email protected]",
    "PasswordSha256": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
    "Active": true,
    "CreatedUtc": "2024-10-21T14:08:41.281865Z"
}

Delete

To delete an object by GUID, call DELETE /v1.0/tenants/[tenant-guid]/users/[user-guid]. Deletion of a user triggers deletion of associated credential objects.

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(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

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


export const deleteUser = async () => {
  try {
    const response = await api.deleteUser(
      "1522f272-c572-4419-88b5-f0a0d37dabf6"
    );
    console.log(response, "User deleted successfully");
  } catch (err) {
    console.log("Error deleting User:", err);
  }
};

deleteUser();

Check Existence

To check existence of an object by GUID, call HEAD /v1.0/tenants/[tenant-id]/users/[user-guid]

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(
  "default", //tenant Id
  "default", //access token
  "http://localhost:8000/" //endpoint
);

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


export const userExists = async () => {
  try {
    const response = await api.existsUser(
      "9b7796bc-b36f-4e68-8cec-4ce98c9be7cd"
    );
    console.log(response, "User exists");
  } catch (err) {
    console.log("Error fetching User:", err);
  }
};

userExists();