Any tool or programming language capable of issuing HTTP requests should be able to use the Tachyon Consumer API . This means you can use your tool of choice.
To help you use the Consumer API we have designed:
Tachyon Server versions from 3.3 have documentation you can access with a web browser. Go to https://<MyTachyonServer>/Consumer/swagger/ui/index#/ (replace <MyTachyonServer> with the address of your Tachyon installation) to view the API documentation .
Use the the built-in swagger documentation as your primary guide regardless of your chosen tool or language and consider Consumer API Reference as back-up source .
Consumers do not have to be purpose-built programs. API testing tools are also considered Consumers. A Python or PowerShell script can also be a Consumer.
Tachyon uses the concept of a Consumer to differentiate the various pieces of software accessing it. It also limits 3rd party software in its use of Tachyon (for example, by defining how many simultaneous instructions a given Consumer can issue) or define where responses to instructions should be offloaded to.
A Consumer is identified by its name and this name has to match between the license, its registration in Tachyon and each API call made. Consumer names are not case sensitive, so "MyConsumer" is considered the same as "MyCoNsUmEr". You can think of a Consumer name as an identifier, a passport if you will, that gains a piece of software access to Tachyon Consumer API. As an example, let's assume that you wish to have your own consumer and you want to call it "ScriptRunner". This means that your license file has to have a Consumer entry with the name="ScriptRunner", you have to register "ScriptRunner" as a Consumer in Tachyon and enable it, and you will have to add X-Tachyon-Consumer header field with the value of "ScriptRunner" to every API call you make using your chosen tool. Don't worry if this sounds complex, we will go through each of these elements on this page.
Many pieces of software can introduce themselves as the same consumer, for instance you can have a set of scripts using the same Consumer. Be aware that all software using the same Consumer shares that Consumer's limits and settings that are set inside Tachyon.
A Consumer must fulfill a number of prerequisites to access Tachyon. Consumers must be:
When all three prerequisites are met, the Consumer is allowed to access Tachyon. The API call will be subject to permissions assigned using Tachyon Role Based Access Control (RBAC) to the Principal making the call.
Consumers must be present in the license file and be enabled.
Look in your license file for an entry like the one below (where [your consumer name here] is the name of your consumer):
<Consumer name="[your consumer name here]" enable="on"> </Consumer>
If you cannot find this entry, please contact 1E Support and ask for an updated license file.
The feature containing your Consumer might look something like this:
<Feature name="Customer A Consumer"> <Consumer name="MyConsumer" enable="on"> </Consumer> </Feature>
The consumer must have enable set to equal "on".
Each time an API call is made, Tachyon checks if the:
The Consumer is checked first, the Principal's permissions are checked second only if the Consumer is successfully verified.
To define what Consumer is issuing the call, add an X-Tachyon-Consumer field to the header of the HTTP call. Because each HTTP call is independent, each call must include this field in its header.
Some API endpoints do not require or check this header, but most do, so it should be included in each Consumer API call.
API endpoints relating to Consumers do not check if the software calling them is a Consumer that meets the three prerequisites listed above. This means Consumers can be added or removed by, for instance, their installation or uninstall processes. Although these API endpoints do not check for the X-Tachyon-Consumer HTTP header, they will always check the permissions of the calling Principal.
A Consumer can be registered (added) directly using the API. All the endpoints responsible for Consumer management are located in the Consumer's controller of the API. This is available under URI. Read the Consumer API reference documentation for details.
A Consumer can also be registered through the Tachyon Settings web application. Browse to Configuration and select the Consumers menu item.
To manage Consumers, the Principal making the call must have Write permission on Consumers' securable type. Set this by assigning the Principal to the Consumer Administrator role.
In addition to the concept of a Consumer, Tachyon has a concept of a Principals. A Principal can be a user or a group taken from Active Directory. While Tachyon does come with at least one Principal that represents a machine account (therefore a local account, not an Active Directory one), this Principal is created during installation for the purpose of internal communication between various Tachyon components and you cannot add non Active Directory Principals yourself.
A Consumer is a piece of software. A Principal is the user of that software. A "user" is something or someone using the software, for example a computer account running a service is a user even though it's not a person. Consumers are subject to Consumer check as described above. Principals are subject to RBAC checks.
It is important to understand how Permissions interact with Consumers and Principals.
Consumers cannot be assigned Permissions. They cannot be limited to only certain Principals either. In short, Consumers have no link or interaction whatsoever with Permissions or Principals.
Principals have Permissions through Roles they are assigned to, as per standard RBAC model.
This means that a Principal will have the same set of Permissions regardless of what Consumer they use.
If you were to launch a web browser and open Tachyon Explorer, you would have exactly the same set of Permissions as if you had opened Guaranteed State application, made an API call through Postman or run a Powershell script that contacts Consumer API.
When Princiapls and Permissions are concerned, the Consumer is irrelevant. Any Consumer can be used, as long as it is licensed and registered in Tachyon. It is only a tool that is used to perform an action. For RBAC what matter is who performs the action.
Tachyon performs two independent checks when it receives an API call:
First we'll try to determine if you can access the API by browsing to https://<MyTachyonServer>/Consumer/Information.
This endpoint doesn't require the X-Tachyon-Consumer field to be present in the request's header so can be made from a web browser.
If everything works you should see a piece of XML that will state the version of the product.
Performing this step will help you establish that everything it up and running and can be accessed via given URL.
Next, access the API using an API testing tool, like Postman www.getpostman.com or Telerik Fiddler https://www.telerik.com/fiddler. With Postman (shown in the picture) remember that not all versions handle Windows Authentication correctly. Please have a look at API testing tools page which discusses several tools and their configuration.
In the examples below we'll use Postman.
First, issue a GET request to https://<MyTachyonServer>/Consumer/SystemInformation
You should see something like the screenshot on the right.
This is because you didn't include X-Tachyon-Consumer in the request header.
Now let us add this field to the header. The example on the right is using "Explorer" as the Consumer name, but you should use the name of you Consumer.
Now when you make the request you should see something like this:
You might see something like this:
Or like this:
In the case of the first error above, you've reached Tachyon and it's telling you the Principal you're using is not authorized. This can mean that it has not been added to Tachyon or does not have permissions to use the endpoint being called. The error you see follows the Tachyon standard error reporting mechanism described in Handling errors returned by Tachyon.
If you get a web page back, like in the second error, it means your request has been rejected by IIS, not Tachyon. This can mean there's a problem with the credentials supplied in the request (incorrect username or password), your IIS settings or the tool you're using. It can also be because your tool does not support Windows Authentication, or because Windows Authentication is disabled. Tachyon uses Windows Authentication for API calls so your chosen tool must support it.
Most API endpoints use application JSON data formatting for expected and returned data.
Be aware that some endpoints take multi-part form-data or in a few cases return an octet stream.
Read the Swagger documentation included in the product or Consumer API reference for the details of all endpoints provided by the Consumer API.
The Tachyon .NET Consumer SDK contains an abstraction layer for the Consumer API. The layer is designed to help build Consumers by abstracting away the complexities of HTTP communication behind C# classes and providing models for the data sent to and received from Tachyon. If you're developing a .NET based application to interface with Tachyon, use the SDK library with the Consumer API reference and How to guides.
Read Tachyon Consumer SDK library for more information.
The Tachyon Offloading SDK provides a managed DLL to use in an ASP.NET application to help create a target for Tachyon offloading. It does not access Tachyon directly, it enables the creation of software Tachyon can access during the offloading process.
Read Tachyon Offloading SDK library for more information.