Permalink: https://doc.oneportal.fi/x/b4AW

There are two different Private Token Stores:

• one which is private to the Management API Client, and
• one which is private to the user account. However, the data stored for user account can be shared between Management API Clients by defining proper ACLs.

These Private Token Stores are used to store simple data in the form of “Key : Value”. The value should always be maximum of 1 megabyte in size, preferably much less. If the values are larger than few kilobytes, it is recommended to monitor performance on large namespaces.

There will later be a Data storage explained functionality to store more complex data structures with proper ACLs, and extensibility.

Maximum token sizes

Maximum total size for all Management API Client tokens is 15 megabytes. The number of tokens is not limited, but each token takes some space, and is counted towards the 15 megabytes. Note, this 15 megabytes limitation is for all tokens combined, not for a one token.

Management API Client Private Token Store

OnePortal has the ability to store third party application data as so-called tokens that consist of three properties. This Token Store may be accessed with Management API Client permissions. These tokens are private to the API Client.

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 onePortal apidoc's 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" 
}

Please note, if ACLs are stored for the token, above example is extended.

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.

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.

Consider the entity relations diagram in Figure 6. 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.

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 the use of 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": "[\"eggs\", \"ham\"]"
}

Using the token endpoints

This section covers the practical details on accessing the Application Private Token API.

Persisting tokens

% todo - APIlle pitäisi lisätä tuki useamman tokenin tallentamiselle yhdelllä POST -pyynnöllä. Dataksi annetaan lista tallenettavista tokeneista.

Querying tokens

% todo - APIin voisi ehkä lisätä tuen kyselyille tokeneita varten esim. GET /token?key=k1&relatedid=id1

User Account Private Token Store

This Token Store is conceptually different. It may be accessed both with Management API Client permissions, or with signed-in user account permissions. These tokens are private to the user account. Unlike Management API Client private tokens, these tokens may be shared between applications and services. To do that, ACLs must be defined. Se here for more information.

https://oneportal.t5.fi/apidoc lists the API end-points under /user/{userID}/token.