Authentication and request IDs
All requests using the TT REST API must include:
- An Application Key in the header
x-api-key=<application key>
Additionally, most requests also require:
- A Token in the header.
Authorization=Bearer <token>-
A request ID passed as a query string
requestId=<app_name>-<company_name>--<new_guid>
Note: The TT REST API documentation provides the ability to create and send test requests. These test requests also need the above-mentioned parameters where required by the endpoint.
Application keys
Application Keys are created using the Setup application. An Application Key is associated with the login used to create it and the key will inherit the login’s permissions and access to data for the environment in which the key was created. Separate application keys are required for making requests from the UAT and Live environments.
Consult the documentation for more information on the environments used by the TT REST API as well as creating application keys.
Tokens
For all TT REST endpoints, users must obtain a token.
To request a token, you send your application key and application secret within a POST request to the ‘/token’ endpoint. Full documentation can be found at the bottom of this page.
When using the token in subsequent requests, Bearer is added to the front of the token you receive.
Note: Tokens are set to expire after a given period of time. This period of time is communicated in the response to your token request as the “seconds_until_expiry” value. Your application will need to generate a new token before its token expires.
Providing a Request ID
All endpoints require a query parameter named requestId. Its value must be of the form:
<app_name>-<company_name>–<new_guid>
where:
- <app_name> is a user-generated string used to identify the specific application making the call.
- <company_name> is a user-generated string used to identify the user’s company.
- <new_guid> is the globally unique identifier for this request. Each separate request should have a distinct identifier so that it can be traced. GUIDs can be created using a GUID generator.
To avoid issues when submitting your request and requestId, you must adhere to the following format requirements:
-
Do not use special characters: TT strongly recommends you avoid using special characters ($ & + , / : ; = ? @ ” <> # % { } | \ ^ ~ [ ] `) when creating your requestId. These characters may cause failures when passed to some TT backend components.
-
Do not include spaces: Your requestId cannot include blank spaces.
-
Match the case sensitivity of the requestId parameter: The request will only work if the query parameter uses the appropriate ‘lower camelcase’ format: requestId. Alternate case structures (e.g., requestid, requestID, or requestiD) may result in a failed request.
Note Requests submitted without the requestId query parameter will be rejected.
Creating a Globally Unique Identifier
To create a unique identifier, you can use an online GUID Generator like guid.one or any other GUID generator available online.
These tools generate completely random values (e.g., 47a1e1c4-0c94-4fb3-94a9-d772382458a3) that meet the criteria for creating a value used for identification.
Note: You must includes all characters, including hyphens, when using this value to access TT REST API.
For additional information on GUID values, visit guid.one/guid.
Using Authentication and request IDs in test calls within documentation
The TT REST API documentation lets you make test calls for endpoints for all services. The Ledger, Monitor and Risk services require a token for addtional authentication. The documentation simplifies the process of authorizing your requests and for specifying a sample value for the new requestId parameter required for requests in these services.
Rather than requiring you to authorize each request individually, the documentation provides an Authorize button that lets you enter the necessary authorization once for all calls in the service. When you click the Authorize button, you can enter the API key and token in the dialog box, as shown.
- Enter your TT REST API Application Key from Setup.
- Enter “Bearer ” followed by the token (include a space, but do not include the quotes).
For any endpoint, you can click the Try it out button, populate the parameters, and execute the test request. While using the documentation to test your requests, a sample requestId parameter, in the proper format, is automatically populated so you need not generate a new GUID for each test request.
Note: The sample requestId is valid only for test calls made from the documentation. When making requests from your application, you must generate a new and unique GUID for every request.
Token Requests
To get a token, you send your application key and application secret within a POST request to generate a token. Expand the ‘/token’ documentation below to view the required parameters for generating a token.