Credentials

Object Overview

Credentials define the access material by which users 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]/credentials

Supported methods include: GET HEAD PUT DELETE

Structure

Objects have the following structure:

{
    "GUID": "default",
    "TenantGUID": "default",
    "UserGUID": "default",
    "AccessKey": "***ault",
    "SecretKey": "***ault",
    "Name": "Default credential",
    "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
UserGUID GUID globally unique identifier for the user
AccessKey string the access key
SecretKey string the secret key
Name string Name of the credential
Active bool indicates whether or not the user is considered active and able to be used
IsProtected bool indicates whether or not the credential is protected
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]/credentials with the following properties using the configuration server: UserGUID

IMPORTANT: the only time the access key and secret key are returned to you is during the create operation. After this, a redacted access key and secret key will be returned to you. Take note of the access key and secret key from the response body.

curl --location --request PUT 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/credentials' \
--header 'content-type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "UserGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "Default credential",
    "Active": true
}

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 createCredential = async () => {
  try {
    const response = await api.createCredential({
      UserGUID: "9b7796bc-b36f-4e68-8cec-4ce98c9be7cd",
      Name: "Default credential",
      Active: true,
    });
    console.log(response, "Credential created successfully");
  } catch (err) {
    console.log("Error creating Credential:", err);
  }
};
createCredential();

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]/credentials. 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-credential",
            ... credential details ...
        },
        { ... }
    ],
    "ContinuationToken": "[continuation-token]"
}

curl --location 'http://view.homedns.org:8000/v2.0/tenants/00000000-0000-0000-0000-000000000000/credentials/' \
--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 enumerateCredentials = async () => {
  try {
    const credentials = await api.enumerateCredentials();
    console.log(credentials, "Credentials fetched successfully");
  } catch (err) {
    console.log("Error fetching Credentials:", err);
  }
};

enumerateCredentials();

Read

To read an object by GUID, call GET /v1.0/tenants/[tenant-guid]/credentials/[credential-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": "6046481e-5682-462a-a1a2-a7e1e242b1ff",
    "TenantGUID": "default",
    "UserGUID": "default",
    "AccessKey": "****ebsr",
    "SecretKey": "****Qzn9",
    "Active": true,
    "CreatedUtc": "2024-10-21T14:33:55.000000Z"
}

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/credentials/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 getCredential = async () => {
  try {
    const credential = await api.retrieveCredential(
      "f734b815-c9ef-403a-8125-cfec4d405482"
    );
    console.log(credential, "Credential fetched successfully");
  } catch (err) {
    console.log("Error fetching Credential:", err);
  }
};
getCredential();

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 objects, call GET /v1.0/tenants/[tenant-guid]/credentials/. If the object exists, it will be returned as an array of JSON object in the response body

curl --location 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/credentials' \
--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 getAllCredentials = async () => {
  try {
    const credentials = await api.retrieveCredentials();
    console.log(credentials, "All credentials fetched successfully");
  } catch (err) {
    console.log("Error fetching Credentials:", err);
  }
};

getAllCredentials();

Delete

To delete an object by GUID, call DELETE /v1.0/tenants/[tenant-guid]/credentials/[credential-guid].

curl --location --request DELETE 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/credentials/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 deleteCredential = async () => {
  try {
    const response = await api.deleteCredential(
      "58051d5c-fb01-4e9a-83f7-f310b4449f15"
    );
    console.log(response, "Credential deleted successfully");
  } catch (err) {
    console.log("Error deleting Credential:", err);
  }
};

deleteCredential();

Check Existence

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

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

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

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

export const credentialExists = async () => {
  try {
    const response = await api.existsCredential(
      "65bcfde5-76de-4866-9259-6698e935b894"
    );
    console.log(response, "Credential exists");
  } catch (err) {
    console.log("Error fetching Credential:", err);
  }
};

credentialExists();