Introduction

10 min read

Concept

Overview

There are two user authentication schemata on the Trusted Twin platform:

• User Secret (API key) based user authentication schema,
• User Token based user authentication schema.

Both schemata use the same authorization model. The model is based on the user role.
Read more: Account and user

A User Secret (API key) and a User Token have different purposes of use:

• A User Secret (API key) is intended for use by backend applications that require access to the Trusted Twin API.
• A User Token is intended for use by frontend applications. It allows for direct access to the Trusted Twin API, bypassing backend applications. A User Token is always generated on the base of a User Secret (API key) and it inherits all permissions of the User Secret (API key).

User Secret (API key)

A User Secret (API key) is always associated with a user. A user can only have one active User Secret (API key) at a given time. The User Secret (API key) serves for user authentication.

Permissions granted to a given User Secret (API key) (i.e., user permissions and rules) are stored in the role of the user for whom the User Secret (API key) was generated. The "validity_ts" is stored as an attribute by the user for whom the given User Secret (API key) was generated.

A change to the user role or an update of the "validity_ts" attribute does not automatically invalidate a User Secret (API key).

User Token

A User Token is always associated with the User Secret (API key) which was used to generate it. You can generate any number of User Tokens  using a single User Secret (API key). The permissions of a User Token are inherited from the User Secret (API key) used to generate it. These permissions are checked during each API call.

When creating a User Token, you can specify the "validity_ts" of a given User Token which will always be subordinate to the "validity_ts" of the User Secret (API key) used to generate a given User Token.

When creating a User Token, you can provide a dictionary containing variables (i.e., "secret_dict") that will be passed to authorization rules and templates in the same way as when using the "X-TrustedTwin" custom header, which allows for personalization of User Tokens. The "secret_dict" is not visible to the user creating the User Token. In case when the "X-TrustedtTwin" header is passed in the API method call authorized with the User Token, the "secret_dict" passed in the User Token takes precedence over variables of the same name passed in the "X-TrustedTwin" custom header.

Developer resources
Custom headers
Rules
Templates

When creating a User Token, you can indicate whether the User Token can be used to create more User Tokens ("create" option)  or to extend the "validity_ ts" of a User Token ("refresh" option).

Important note

Refreshing an existing User Token does not automatically invalidate the User Token used to refresh that User Token. You should treat a “refreshed” User Token  as a copy of this User Token with updated validity (i.e, the "secret_dict" is inherited from the User Token that was used to refresh it). 

Because User Tokens are always subordinate to the User Secret (API key) used to generate it, invalidating a User Secret (API key) automatically invalidates all User Tokens which were generated on the base of this User Secret (API key). 

Best practices

• We recommend creating a dedicated user and User Secret (API key) for generating User Tokens with limited permissions.
• We recommend using a "secret_dict" to limit User Token access to only selected resources (e.g., Twins, Entries, Identities).
• Remember that invalidating a User Secret (API key) automatically invalidates all User Tokens associated with the User Secret (API key).
• Remember that User Tokens always inherit permissions from current settings of the user role associated with the User Secret (API key) used to generate the User Token.