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:
Each API is expandable, by clicking on it, you can view additional information about the API.
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/docs/index.html NoteContent Distribution documentation is not readily available, please follow these steps to enable it.
|
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
Fiddler
In Fiddler check Automatically Authenticate on the Composer->Options tab.
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:
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:
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.