Application Private Tokens

Basics

Trivore Identity Service (TIS) has the ability to store third party application data as so-called tokens, that consist of three properties. This Token Store may be accessed by Management API Clients. These tokens are private to the API Client. This means that no Management API Client will be able to see the tokens of another Management API Client. However, the user who is the owner of the Management API Client will be able list all tokens in the Web UI in the Application Tokens view.

The token handling is done in the Management API documented earlier. In the API all the token endpoints are under the /token endpoint. The API is subject to change, so the reader is advised to refer to the TIS platform's /apidoc Application Private Tokens section.

The tokens consist of a related id, key and a value. An example of a token is shown below.

{ 
    "relatedId": "string", 
    "key": "string", 
    "value": "string" 
}

The relatedId is a string, which is used as an id reference to other tokens. The upcoming examples will demonstrate the use of the relatedId attribute. The key can be considered the name of the token. It can be thought to be a field name in a relational database. The value attribute contains the actual value of the token. The value is always encoded as a string so if you want to insert JSON document as a value you will have to escape it.

Limitations

There are some technical limitations on how application private tokens can be used. Please be aware of them when designing your usage patterns for the tokens.

Maximum token sizes

Maximum token size is 16 MB and there is technically no limit on how many tokens a Management API client can have.  However, having lots of large tokens may eventually lead to problems in performance, especially when listing a large number of tokens.

Naming

It is not recommended to use dots (.) in the values of key and relatedId attributes. The dot is a meaningful character in the DBMS used and may interfere with the underlying filtering mechanism.

Conventions

Keeping consistency across token structures, naming and data structures within tokens is crucial in order to maintain an application utilizing tokens. This section gives some recommendations on how to maintain consistency when using Application Tokens. Still, however, these are only recommendations and in the end the application designers can use whichever conventions they choose.

It is recommended to use the entity ID as the related id. An attribute name should be used as the token key and the attribute's value as the token's value.

When persisting lists, it is recommended to use the JSON syntax. For example a list of words in JSON could be ["apples", "oranges"].

Additionally, tokens can be used to hold complex arbitrary data structures as embedded JSON objects. The JSON objects have to be escaped when persisting.

Example: Mapping an entity relation to tokens

Mapping an entity relation to tokens may not be obvious at first. This section will walk through a simple example of mapping an entity relation model to tokens. The TIS Management API token endpoint is documented in the TIS instance's /apidoc. See Management API for more detailed instructions on how to get the most current documentation for the Management API.

Consider the entity relations diagram above. There are projects, which has one or more products. The projects also have n employees assigned. Additionally, an employee can be assigned to m projects. The project has an id, a human readable name and a list of key words. A product has an id and a name. An employee has an id, name and an email address.

Creating the project entity

When starting with project creation, the first token to create could be

{
    "relatedId": "project1",
    "key": "name",
    "value": "The project number one"
}

In the token above, for the sake if readability project1 is used as an unique id for the project (underlined). It is up to the application to keep track of related IDs and ensure that they are unique across the token store. One way to ensure this would be to use UUIDs.

After the first token is created the data store has one project with a single attribute. To add another attribute persist a token shown below. Note the JSON escaping in the list.

{
    "relatedId": "project1",
    "key": "key_words",
    "value": "[\"foo\", \"bar\"]"
}

Creating the product entity

We can start creating the product entity by giving it a name.

{
    "relatedId": "product1",
    "key": "name",
    "value": "apples"
}

After creating the product, we can create a token to represent the relation between the product and the project.

{
    "relatedId": "product1",
    "key": "project",
    "value": "project1"
}

Creating the employee entity

The employee is a simple entity with id, name and email address. We will start by creating a token with a name.

{
    "relatedId": "employee1",
    "key": "name",
    "value": "John Doe"
}

After that we may create a token with an email address.

{
    "relatedId": "employee1",
    "key": "email",
    "value": "[email protected]"
}

After we have the basic object created, we can create the relation between the employee and the project:

{
    "relatedId": "employee1",
    "key": "project",
    "value": "[\"project1\"]"
}

If the employee is part of many projects, then we can append the project IDs to the list.

The above steps can be repeated after all project employee info has been saved.

Querying objects

When we want to read the created objects, we will have to query them from the token endpoint.

Listing all tokens

Listing all tokens with filter support will be implemented soon.

Listing tokens based on relatedId and key

Tokens can be listed using the related id. This allows getting all properties for a single entity. For example, we could use the relatedId "employee1" to retrieve the name and email for the employee. Additionally, if we only want to fetch the name of the employee, we can get a single token by relatedId and key. Getting single tokens is extremely useful in situations where the size of the token is more than a few kilobytes.