View Authentication API Reference

Overview

The View Authentication API provides secure access control for the View platform through multiple authentication methods. This comprehensive guide covers all authentication operations including token generation, validation, and user management.

Authentication Methods

View supports several authentication approaches:

Password Authentication: Traditional email/password login
SHA-256 Password Authentication: Enhanced security with pre-hashed passwords
Administrator Authentication: Special admin-level access tokens
Token Validation: Verify and retrieve token details

Key Features

Multi-tenant support with tenant-specific authentication
Secure token-based authentication with expiration
Administrator-level access controls
Comprehensive token validation and details retrieval
Support for multiple programming languages and SDKs

Retrieve Tenants for Email

Retrieves all tenants associated with a specific email address using GET /v1.0/token/tenants. This is typically the first step in the authentication process to determine which tenants a user has access to.

Request Parameters

x-email (string, Header, Required): The email address to query for associated tenants

curl --location 'http://view.homedns.org:8000/v1.0/token/tenants' \
--header 'x-email: [email protected]' \
--header 'Authorization: ••••••'

import { ViewConfigurationSdk } from "view-sdk";

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

const retrieveTenantsForEmail = async () => {
  try {
    api.config.accessToken = 'your-access-token-here';
    const tenants = await api.Authentication.retrieveTenantsForEmail('[email protected]');
    console.log('Tenants fetched successfully:', tenants);
  } catch (err) {
    console.error('Error fetching tenants:', err);
  }
};

retrieveTenantsForEmail();

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 get_tenants_for_email():
    try:
        tenants = configuration.Authentication.retrieve_tenants_for_email("[email protected]")
        print("Tenants retrieved successfully:", tenants)
    except Exception as e:
        print(f"Error retrieving tenants: {e}")

get_tenants_for_email()

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

public static class Example 
{
    public static async Task Main(string[] args)
    {
        ViewConfigurationSdk sdk = new ViewConfigurationSdk(
            Guid.Parse("00000000-0000-0000-0000-000000000000"),
            "default", 
            "http://view.homedns.org:8000/"
        );
        
        Console.Write("Enter your email: ");
        string email = Console.ReadLine();
        
        sdk.Email = email; 
        sdk.Password = null;
        sdk.PasswordSha256 = null;
        sdk.TenantGUID = null;
        sdk.XToken = null;
        
        try 
        {
            List<TenantMetadata> tenants = await sdk.Authentication.RetrieveTenants();
            Console.WriteLine("Tenants retrieved successfully:");
            foreach (var tenant in tenants)
            {
                Console.WriteLine($"- {tenant.Name} (GUID: {tenant.GUID})");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error retrieving tenants: {ex.Message}");
        }
    }
}

Response:

[  
   {  
    GUID: '00000000-0000-0000-0000-000000000000',  
    parentGUID: null,  
    name: 'Default Tenant',  
    region: 'us-west-1',  
    s3BaseDomain: '',  
    restBaseDomain: 'localhost',  
    defaultPoolGUID: '00000000-0000-0000-0000-000000000000',  
    active: true,  
    createdUtc: '2025-03-25T21:12:32.461527Z',  
    accountGUID: '00000000-0000-0000-0000-000000000000',  
    isProtected: true  
  }
]

Generate Authentication Token (Password)

Generates an authentication token using email and password credentials using POST /v1.0/token. This is the standard authentication method for user login.

Request Parameters

x-email (string, Header, Required): User's email address
x-password (string, Header, Required): User's password
x-tenant-guid (string, Header, Required): GUID of the tenant to authenticate against

curl --location 'http://view.homedns.org:8000/v1.0/token' \
--header 'x-email: [email protected]' \
--header 'x-password: password' \
--header 'x-tenant-guid: 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
);

const generateAuthenticationToken = async () => {
  try {
    const response = await api.Authentication.generateAuthenticationTokenByPassword({
      email: "[email protected]",
      password: "password",
      tenantGUID: "00000000-0000-0000-0000-000000000000",
    });
    console.log("Authentication token generated successfully:", response);
  } catch (err) {
    console.error("Error generating authentication token:", err);
  }
};

generateAuthenticationToken();

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 get_authentication_token():
    try:
        token = configuration.Authentication.generate_authentication_token(
            "[email protected]",
            "password",
            "00000000-0000-0000-0000-000000000000"
        )
        print("Authentication token generated successfully:", token)
    except Exception as e:
        print(f"Error generating authentication token: {e}")

get_authentication_token()

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

public static class Example 
{
    public static async Task Main(string[] args)
    {
        ViewConfigurationSdk sdk = new ViewConfigurationSdk(
            Guid.Parse("00000000-0000-0000-0000-000000000000"),
            "default", 
            "http://view.homedns.org:8000/"
        ); 
        
        sdk.Email = "[email protected]";
        sdk.Password = "password";
        sdk.PasswordSha256 = null;
        sdk.TenantGUID = "00000000-0000-0000-0000-000000000000";
        sdk.XToken = null;
        
        try 
        {
            AuthenticationToken response = await sdk.Authentication.GenerateTokenWithPassword();
            Console.WriteLine("Authentication token generated successfully:");
            Console.WriteLine($"Token: {response.Token}");
            Console.WriteLine($"Expires: {response.ExpirationUtc}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error generating authentication token: {ex.Message}");
        }
    }
}

Response

{
  "TimestampUtc": "2025-04-02T06:44:16.540236Z",
  "ExpirationUtc": "2025-04-03T06:44:16.540202Z",
  "IsExpired": false,
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "Valid": true
}

Generate Authentication Token (SHA-256)

Generates an authentication token using email and SHA-256 hashed password using POST /v1.0/token. This method provides enhanced security by using pre-hashed passwords.

Request Parameters

x-email (string, Header, Required): User's email address
x-password-sha256 (string, Header, Required): SHA-256 hash of the user's password
x-tenant-guid (string, Header, Required): GUID of the tenant to authenticate against

curl --location 'http://view.homedns.org:8000/v1.0/token' \
--header 'x-email: [email protected]' \
--header 'x-password-sha256: 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8' \
--header 'x-tenant-guid: 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
);

const generateAuthenticationTokenBySHA256 = async () => {
  try {
    const response = await api.Authentication.generateAuthenticationTokenBySHA256({
      email: "[email protected]",
      passwordSHA256:
        "*********************",
      tenantGUID: "<tenant-guid>",
    });
    console.log(response, "Authentication token generated successfully");
  } catch (err) {
    console.log("Error generating Authentication token:", err);
  }
};

generateAuthenticationTokenBySHA256();

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 getAuthenticationTokenSha256():
    token = configuration.Authentication.generate_authentication_token_sha_256(
        "[email protected]",
        "*********************",
        "tenant-guid"
    )
    print(token)

getAuthenticationTokenSha256()

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

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("00000000-0000-0000-0000-000000000000"),"default", "http://view.homedns.org:8000/"); 
sdk.Email = "[email protected]";;
sdk.Password = null;
sdk.PasswordSha256 = "ab******************************";
sdk.TenantGUID = "default";
sdk.XToken = null;

AuthenticationToken token = await sdk.Authentication.GenerateTokenWithPasswordSha256();

Response:

{
  "TimestampUtc": "2025-04-02T06:52:02.837124Z",
  "ExpirationUtc": "2025-04-03T06:52:02.837094Z",
  "IsExpired": false,
  "Token": "*****",
  "Valid": true
}

Generate Administrator Token (Password)

Generates an administrator-level authentication token using email and password credentials using POST /v1.0/token. Administrator tokens provide elevated privileges for system management operations.

Request Parameters

x-email (string, Header, Required): Administrator's email address
x-password (string, Header, Required): Administrator's password

curl --location 'http://view.homedns.org:8000/v1.0/token' \
--header 'x-email: [email protected]' \
--header 'x-password: viewadmin' \
--header 'Authorization: ••••••'

import { ViewConfigurationSdk } from "view-sdk";

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

const generateAdminToken = async () => {
  try {
    const response = await api.Authentication.generateAdministratorToken({
      email: "[email protected]",
      password: "*********",
    });
    console.log(response, "Admin token generated successfully");
  } catch (err) {
    console.log("Error generating Admin token:", err);
  }
};

generateAdminToken();

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 getAdministratorToken():
    token = configuration.Authentication.retrieve_administrator_token(
        email="[email protected]",
        password="default"
    )
    print(token)

getAdministratorToken()

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

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("00000000-0000-0000-0000-000000000000"),"default", "http://view.homedns.org:8000/"); 

sdk.Email = "[email protected]";
sdk.Password = "abc****";
sdk.PasswordSha256 = null;
sdk.TenantGUID = null;
sdk.XToken = null;

AuthenticationToken token = await sdk.Authentication.GenerateAdminTokenWithPassword();

Response:

{
  "TimestampUtc": "2025-04-02T06:52:02.837124Z",
  "ExpirationUtc": "2025-04-03T06:52:02.837094Z",
  "IsExpired": false,
  "Token": "*****",
  "Valid": true
}

Generate Administrator Token (SHA-256)

Generates an administrator-level authentication token using email and SHA-256 hashed password using POST /v1.0/token. This method provides enhanced security for administrator authentication.

Request Parameters

x-email (string, Header, Required): Administrator's email address
x-password-sha256 (string, Header, Required): SHA-256 hash of the administrator's password

curl --location 'http://view.homedns.org:8000/v1.0/token' \
--header 'x-email: [email protected]' \
--header 'x-password-sha256: e75255193871e245472533552fe45dfda25768d26e9eb92507e75263e90c6a48' \
--header 'Authorization: ••••••'

import { ViewConfigurationSdk } from "view-sdk";

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

const generateAdministratorTokenBySHA256 = async () => {
  try {
    const response = await api.Authentication.generateAdministratorTokenBySHA256({
      email: "[email protected]",
      passwordSHA256:
        "****************",
    });
    console.log(response, "Administrator token generated successfully");
  } catch (err) {
    console.log("Error generating Administrator token:", err);
  }
};

generateAdministratorTokenBySHA256();

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 getAdministratorTokenSha256():
    token = configuration.Authentication.retrieve_administrator_token_sha_256(
        email="[email protected]",
        password= "****************"
    )
    print(token)

getAdministratorTokenSha256()

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

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("00000000-0000-0000-0000-000000000000"),"default", "http://view.homedns.org:8000/"); 
sdk.Email = "[email protected]";
sdk.Password = null;
sdk.PasswordSha256 = "adb*************************";
sdk.TenantGUID = null;
sdk.XToken = null;

AuthenticationToken token = await sdk.Authentication.GenerateAdminTokenWithPasswordSha256();

Response:

{
  "TimestampUtc": "2025-04-02T07:03:54.516294Z",
  "ExpirationUtc": "2025-04-03T07:03:54.516265Z",
  "IsExpired": false,
  "Token": "*****",
  "Valid": true
}

Validate Authentication Token

Validates an existing authentication token to check if it's still valid and not expired using GET /v1.0/token/validate. This is useful for checking token status before making authenticated requests.

Request Parameters

x-token (string, Header, Required): The authentication token to validate

curl --location 'http://view.homedns.org:8000/v1.0/token/validate' \
--header 'x-token: *****' \
--header 'Authorization: ••••••'

import { ViewConfigurationSdk } from "view-sdk";

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

const validateToken = async () => {
  try {
    const response = await api.Authentication.validateAuthenticationToken({
      token:"*****",
    });
    console.log(response, "Token validated successfully");
  } catch (err) {
    console.log("Error validating token:", err);
  }
};

validateToken();

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 validateAuthenticationToken():
    token = configuration.Authentication.validate_authentication_token(token="*****")
    print(token)

validateAuthenticationToken()

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

public static class Example {
    public static async Task Main(string[] args)
    {
      ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("00000000-0000-0000-0000-000000000000"),"default", "http://view.homedns.org:8000/"); 
        Console.Write("Enter your email: ");
        string email = Console.ReadLine();
        
        Console.Write("Enter your password: ");
        string password = Console.ReadLine();

        sdk.Email = null;
        sdk.Password = null;
        sdk.PasswordSha256 = null;
        sdk.TenantGUID = null;
        sdk.XToken = "default";

        AuthenticationToken token = await sdk.Authentication.ValidateToken();
        Console.WriteLine(token);
    }
}

Response:

{
  "TimestampUtc": "2025-04-02T07:08:54.577789Z",
  "ExpirationUtc": "2025-04-03T07:06:25.427405Z",
  "IsExpired": false,
  "Valid": true
}

Retrieve Token Details

Retrieves detailed information about an authentication token including user details and expiration information using GET /v1.0/token/details. This endpoint provides comprehensive token metadata for debugging and user management purposes.

Request Parameters

x-token (string, Header, Required): The authentication token to retrieve details for

curl --location 'http://view.homedns.org:8000/v1.0/token/details' \
--header 'x-token: ******' \
--header 'Authorization: ••••••'

import { ViewConfigurationSdk } from "view-sdk";

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

const getTokenDetails = async () => {
  try {
    const response = await api.Authentication.retrieveTokenDetails({
      token:"*******",
    });
    console.log(response, "Token details fetched successfully");
  } catch (err) {
    console.log("Error fetching Token details:", err);
  }
};

getTokenDetails();

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 retrieveTokenDetails():
    token = configuration.Authentication.retrieve_token_details(token="*****")
    print(token)

retrieveTokenDetails()

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

ViewConfigurationSdk sdk = new ViewConfigurationSdk(Guid.Parse("00000000-0000-0000-0000-000000000000"),"default", "http://view.homedns.org:8000/"); 
sdk.Email = null;
sdk.Password = null;
sdk.PasswordSha256 = null;
sdk.TenantGUID = null;
sdk.XToken = "default";

AuthenticationToken token = await sdk.Authentication.RetrieveTokenDetails();

Response:

{
  "TimestampUtc": "2025-04-02T07:06:25.427406Z",
  "ExpirationUtc": "2025-04-03T07:06:25.427405Z",
  "IsExpired": false,
  "AccountGUID": "00000000-0000-0000-0000-000000000000",
  "TenantGUID": "00000000-0000-0000-0000-000000000000",
  "UserGUID": "00000000-0000-0000-0000-000000000000",
  "User": {
    "GUID": "00000000-0000-0000-0000-000000000000",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "FirstName": "Default",
    "LastName": "User",
    "FullName": "Default User",
    "Notes": "Default password is password",
    "Email": "[email protected]",
    "PasswordSha256": "************************************************************42d8",
    "Active": true,
    "IsProtected": true,
    "CreatedUtc": "2025-03-25T21:12:32.461527Z"
  },
  "Valid": true
}

Best Practices

When implementing authentication with the View platform, consider the following recommendations:

Secure Token Storage: Store tokens securely and never expose them in client-side code
Token Refresh: Implement proper token refresh mechanisms before expiration
Enhanced Security: Use SHA-256 authentication for enhanced security when possible
Token Validation: Always validate tokens before making authenticated requests
Administrator Access: Use administrator tokens only for system management operations

Next Steps

After successfully authenticating with the View platform, you can:

Access Protected Resources: Use your authentication token to access tenant-specific data and operations
Manage User Sessions: Implement token refresh mechanisms to maintain active sessions
Implement Role-Based Access: Leverage administrator tokens for elevated privilege operations
Integrate with Applications: Incorporate authentication flows into your applications using the provided SDKs
Monitor Authentication: Use token validation endpoints to check session status