Skip to main content

1E 23.11 (SaaS)

Consumer API reference

Each API endpoint is documented on a separate page. Pages are version controlled.

Overview

This page lists every endpoint provided by the Consumer API which is a RESTful API consumed by the Endpoint Troubleshooting UI and other Consumers. Although 1E has other APIs, the Consumer API is the only one supported for use by third party Consumers.

The URL used for requests is https://{tachyonConsumerServer}/Consumer/{request}

The text shown in example responses is spaced out for readability, normally they are compacted JSON on a single line with no white space between fields to minimize transmitted data.

API endpoints can be viewed and tested using a tool like the Postman, Fiddler or Advanced REST client extension for Chrome, but your chosen tool must support Windows Authentication.

Note

In lab and test environments it's possible to configure 1E to use Basic Authentication over HTTPS using tools that only support this protocol where you would pass credentials explicitly rather than rely on NTLM challenge/response authentication.

This is useful where the account context in which the API call is made is not the account context in which you'd like the call processed. For example, when interacting with subsystems such as Workflow you may wish to make calls in the context of the requester and the responder but without having to switch interactive desktop sessions as the caller.

Exploring the API using a web browser

Although the Consumer API is documented in the child pages to this page, you can also explore it using the inbuilt API documentation. This is available through your browser and managed through the Swagger subsystem by browsing to the Consumer reference.

https://<tachyon server>/Consumer/swagger

Where <tachyon server> is the URL of your Tachyon server, which redirects to the API reference page:

233276540.png

Each API is expandable, by clicking on it, you can view additional information about the API.

233276539.png
Swagger URL reference for 1E platform

Where <tachyon server> is the URL of your 1E server, which redirects to the API reference page.

Component

URL

1E Portal

https://<tachyon server>/Tachyon/swagger/ui/index

1E Consumer

https://<tachyon server>/consumer/swagger/ui/index

1E Experience Analytics

https://<tachyon server>/experience/swagger/ui/index

SLA Admin

https://<tachyon server>/admin/swagger/ui/index

SLA Platform

https://<tachyon server>/platform/swagger/ui/index

Content Distribution

https://<tachyon server>/ContentDistribution/swagger/ui/index

Note

Content Distribution documentation is not readily available, please follow these steps to enable it.

  1. Locate %ProgramFiles%\1E\ContentDistribution\Web\WebService\appsettings.json

  2. Add the AllowSwagger key in the AppSettings section. The settings should look like "AllowSwagger": true

  3. Reset the IIS.

Tool settings

Authentication Mechanisms should be read in conjunction with this page to understand the different options available

Postman

In Postman this setting and the Authentication, varies from version to version. For example, in the Chrome App version it's done automatically when No Auth option is selected.

In new standalone application, you should select the relevant type of Authentication

233276541.png

Fiddler

In Fiddler check Automatically Authenticate on the Composer->Options tab.

233276542.png

Advanced REST client

Google App Runtime for Chrome (ARC) requires the XHR extension turned on (the triple dot menu, top right of the window).

Authentication Mechanisms - Introduction

This page covers authentication methods supported by the 1E platform, focusing on the differences between “legacy” Integrated Windows Authentication mode and “modern” token-based system that integrates with OAuth.

Types of Authentication Available

If you’re using 1E 8.1, only Integrated Windows Authentication is available and your IIS must have Windows Authentication enabled and Anonymous Authentication disabled.

If you’re using 1E version greater than 8.1, only token-based authentication is available and your IIS must have Windows Authentication disabled and Anonymous Authentication enabled.

Which specific identity provider is supported depends on particular version of 1E. For instance, in 8.2 AzureAD is supported while 8.3 adds support for Okta. Please consult documentation specific to your version of 1E for a complete list and information on how to configure each Identity Provider (IdP).

Integrated Windows Authentication

This was the original authentication method. It is based on Windows accounts, either local or domain, where domain accounts would be used by users and groups while local accounts would be used by services.

Integrated Windows Authentication - The Basics

The burden of handling authentication rests on Windows itself. A REST call via a tool or a browser would have to contain appropriate Windows credentials and IIS would require those via a 401 negotiation.

In most cases, authentication is automatic because a user is logged into a domain and therefore their credentials are available and can be supplied without user inputing them in. In some circumstances (such as running the browser in incognito mode) the browser would display a popup requesting credentials from the user, but in most cases authentication is invisibly handled by IIS and the browser.

Token based authentication and OAuth support - Contacting the API

Once you have a Token you can call 1E APIs.

To do so, set your authentication to “no authentication” and add a header field called “X-Tachyon-Authenticate“ into your request. The value of this field should be the Token. Do not add any extra characters, quotes or anything else like that. The value of this field is expected to be just the token.

Here’s an example of how this would look in Postman:

Contacting_the_API_in_Postman.png
Token based authentication and OAuth support

Token based authentication is abstracted from any particular authentication system and completely independent from Windows.

Token based authentication and OAuth support - The basics

This system will rely on an external IdP provider (usually an OAuth compliant one like AzureAD or Okta) to handle authentication process as far as verifying user names and passwords in concerned.

This system will not, however, rely on tokens issued by said IdP as an authentication method inside 1E. Instead, 1Ewill issue its own cryptographicaly signed tokens based on the IdP’s tokens.

This means that a token needs to be requested and logging in is no longer an automatic affair as it was with Integrated Windows Authentication.

Instead, the user must begin their interaction with 1E by requesting authentication. A response to this request will be a web address that points to the configured IdP. There the user will input their credentials and log into their IdP (be that AzureAD, Okta or another provider) as they would for any other website. Afterwards, if the authentication was successful, the IdP will call 1E back to notify it of successful authentication. At that point 1E will obtain IdP’s token, keep it and exchange it for one of it’s own tokens that it will give to the caller who requested authentication.

So, the end result of an authentication request should be a token.

Token based authentication and OAuth support - How the system works

Contacting the API requires a Token.

In order to obtain a Token, you have to complete an authentication request through the 1E platform. This will entail requesting authentication from the platform and authenticating with your IdP. Once that is complete, you will receive a Token.

From that point onwards, you should add that token every API request you make. Not just to Consumer API, but every API in the 1E platform.

Token based authentication and OAuth support - Obtaining a taken

Token based authentication and OAuth support - Interactive login

In order to obtain a Token you have to make a GET request to wss://your.tachyon.server/Tachyon/api/Authentication/RequestAuthentication.

This request must be made using websocket protocol in order to maintain constant connection throughout the entire authentication process. Should the connection be interrupted for whatever reason before the authentication has finished, you will have to start again. Resuming authentication or polling aren’t supported.

Once the above request is made, you will receive a redirect HTTP code and a URL address to follow. This address should be used to authenticate with your configured IdP. Once that is successful and the IdP has called 1E back (please note you will not be aware of this taking place as it will be the IdP calling 1E API directly) you will receive your Token through the websocket connection. At this point the authentication request is considered complete and websocket connection can be closed.

Token based authentication and OAuth support - Non-interactive Login

You can also obtain a Token using a JWT you already have.

In order to do so you should make a POST request to https://your.tachyon.server/Tachyon/api/Authentication/RequestJwtAuthentication and provide your token in the body of the request. This endpoint expects a string so your token needs to be wrapped in double quotes in the payload.If the JWT is valid you will receive a Token in return.

Token based authentication and OAuth support - The toolkit

The toolkit has the ability to retrieve a Token.

Please consult toolkit’s documentation for details: 1E PowerShell Toolkit management cmdlet reference.

Token based authentication and OAuth support - Handling Tokens

Token based authentication and OAuth support - Token types

There are two main types of Token, an interactive token that represents a user or a group, and a non-interactive token that represents an element of 1E platform, an API, a service or another piece of software.

Token based authentication and OAuth support - Token Types - Interactive

This is the token you will be obtaining sing the authentication mechanisms (both interactive and JWT) described above. This type of token has two subtypes.

First subtype is the fully interactive type, obtained via interactive login as described above. These tokens can be refreshed (see below) up to a number of times defined in your configuration.

Second subtype is the semi-interactive, obtained by supplying a JWT. These tokens cannot be refreshed. You need to obtain a new JWT and supply it to the API to obtain a fresh Token.

Beyond the refresh, the two token subtypes are functionally identical.

Token based authentication and OAuth support - Token Types - Non-interactive

This type of token is used by 1E internally. You will not be able to obtain this type of token.

Token based authentication and OAuth support - Token lifecycle

Fully interactive tokens can be refreshed. This is done by making a POST request to https://your.tachyon.server/Tachyon/api/Authentication/RefreshToken and providing the token you’d like to refresh in the body of the request. This endpoint expects a string so your token needs to be wrapped in double quotes in the payload.

Tokens can only be refreshed a certain number of times before you will be forced to perform the authentication from scratch. Appropriate error will be returned by the API when that happens.

You can log out of the system by calling https://your.tachyon.server/Tachyon/api/Authentication/Logout. This is a GET request that does not need any parameters, but it needs to have a token in the header field (see below). This will remove the ability of the token to be refreshed, effectively ending the “session”, though for technical reasons your token will remain valid for the remainder of its lifetime.

Logging out is optional and you can simply opt to “forget” the token. Information about your session will be automatically cleaned up after your token expires.

Token based authentication and OAuth support - Contacting the API

Once you have a Token you can call 1E APIs.

To do so, set your authentication to “no authentication” and add a header field called “X-Tachyon-Authenticate“ into your request. The value of this field should be the Token. Do not add any extra characters, quotes or anything else like that. The value of this field is expected to be just the token.

Here’s an example of how this would look in Postman:

Contacting_the_API_in_Postman.png
Error Conditions

If an error occurs, for example you use /Consumer/InstructionDefinitions/33333 when there are only 23 instruction definitions, the Consumer API returns a 404 error and XML error message, for example:

HTTP/1.1 404 Not Found 
 Cache-Control: no-cache 
 Pragma: no-cache 
 Content-Type: application/xml; charset=utf-8 
 Expires: -1 
 Server: Microsoft-IIS/10.0 
 X-AspNet-Version: 4.0.30319 
 Persistent-Auth: true 
 X-Powered-By: ASP.NET 
 Date: Thu, 04 Feb 2016 11:34:59 GMT 
 Content-Length: 142 
{ 
  "Message": "No HTTP resource was found that matches the request URI ' https://tachyondogfood.1e.local/Consumer/InstructionDefinitions/33333 '."
 }
Consumer API SDK assembly

From v1.7 Tachyon provides an assembly to consume Consumer API. This assembly is versioned and wraps all the consumer API end points available in a version.

Release Notes
Api changes between Tachyon 4.0 and 4.1

There have been no API endpoints introduced, deprecated or removed in version 4.1.

Api changes between Tachyon 4.1 and 5.0
  • Consumer/PrincipalSearch method using GET verb is now deprecated and will be removed in a future version. Please use Consumer/PrincipalSearch using POST verb instead.

  • Consumer/PrincipalSearch method using POST verb has been added to augment Active Directory user and group search with the capability to request limiting the number of results returned, define sorting and explicitly specify type of AD objects to search (users, groups or both)

  • Consumer/SystemInformation/IsConsumerLicensed/Name/{name} method using GET verb has been added to allow checking consumer's licensed status by consumer name.

  • Consumer/SystemInformation/IsConsumerLicensed/Id/{id} method using GET verb has been added to allow checking consumer's licensed status by consumer Id.

  • Consumer/SystemInformation/LicensedConsumers method using GET verb has been added to allow retrieval of all licensed consumers.

  • Consumer/EventSubscriptionAssignments API has been introduced. It has 5 methods. This API and its methods have been introduced to support eventing mechanism.

  • Consumer/EventSubscriptions API has been introduced. It has 10 methods. This API and its methods have been introduced to support eventing mechanism.