Management

In order for a T1C-API to be downloadable from and be able to register with the Distribution Service, a few steps must be executed.

Management User Interface

Will be added later

REST API

We offer a Postman collection of the DS REST API which you can use. Below we will provide more information on the endpoints and their parameters.

Obtain IDP Token

For the management endpoints a user JSON web token is necessary. it can be obtained from the IDP and must be included in all management requests to the DS REST API as a bearer token

Example

curl --location --request POST 'https://[[IDP_URL]]/auth/realms/[[T1C_REALM]]/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=trust1connector' \
--data-urlencode 'username=[[USER]]@trust1team.com' \
--data-urlencode 'password=[[PASSWORD]]' \
--data-urlencode 'grant_type=password'

Request

Note that the request is x-www-form-urlencoded

Property	Type	Description
client_id	String	The ID of the client you created in the IDP realm
username	String	The username of the user you created in the IDP realm
password	String	The password of the user you created in the IDP realm

The response will contain an access_token property value which can be used in management requests made to the DS REST API.

Sample response

{
    "access_token": "eyJhb...DSLG0g",
    "expires_in": 864000,
    "refresh_expires_in": 864000,
    "refresh_token": "eyJhb...oXsaQ",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "5ee8573e-63b7-4975-a20a-1355493ec17e",
    "scope": "email profile"
}

Create Or Update Version

It is necessary to create a version in order to have a valid registration API key for the installer packages

Example

curl --location --request PUT 'http://localhost:8000/v3/versions' \
    --header 'Authorization: Bearer eyJh...olw' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "id": "3.1.1",
        "recommended": false,
        "mandatory": false,
        "allowed": true,
        "uris": [
            {
                "os": "MACOS",
                "uri": "https://storage.googleapis.com/deps_t1c/mac/v3.1.1/Release/Trust1Connector.dmg"
            },
            {
                "os": "WIN32",
                "uri": "https://storage.googleapis.com/deps_t1c/win/v3.1.1/Release/T1C-API_x86.exe"
            },
            {
                "os": "WIN64",
                "uri": "https://storage.googleapis.com/deps_t1c/win/v3.1.1/Release/T1C-API_x64.exe"
            },
            {
                "os": "UNIX",
                "uri": "https://storage.googleapis.com/deps_t1c/unix/v3.1.1/Release/Trust1connector.deb"
            }
        ],
        "installationApiKey": "8a313cec-a2fd-4fbc-9408-86afaa3a3e1a"
    }'

Request

Property	Type	Description
id	String	The version ID must be valid according to Semantic Versioning and unique. This value is used to determine the latest version.
recommended	Boolean	If set to true, older versions will display an OS dialog with a download link to this recommended version when performing an update check. If false, no dialog will be shown to the T1C-API user.
mandatory	Boolean	If set to true, every older version of the T1C-API performing an update check will display a message with a download link and shut down. This means that previous versions of the T1C-API will no longer function.
allowed	Boolean	If set to false, when T1C-API of that version will shut down after performing an update check. This differs from the mandatory property in that this offers a mechanism to force users of a specific version to the latest version, without impacting users of other versions.
uris.os	Enum	Accepted values are: WIN32, WIN64, MACOS, UNIX. This determines for which OS the installer package is meant.
uris.uri	String	The URI for this versions installer package for a specific OS. The URI can be of a file hosted online or of a file hosted on the server filesystem, e.g. https://domain/path/package or file:///path/package
installationApiKey	UUID	This is the API key that is included in the installer package for the initial registration. If not provided, a random UUID will be generated and added to the Kong gateway registration consumer. This value must match the value in your installer packages.

Create Or Update Context Config

The context config contains variable configuration for the installed T1C-API packages

Example

curl --location --request PUT 'http://localhost:8000/v3/configurations' \
    --header 'Authorization: Bearer eyJh...olw' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "config": {
            "cors": [
                "https://t1c.t1t.io",
                "http://t1c.t1t.io",
                "http://localhost:3000",
                "https://acc-ds.t1t.io",
                "https://t1c.t1t.io:51983"
            ]
        },
        "type": "CONTEXT_CONFIG",
        "versionId": "3.1.1"
    }'

Request

Property	Type	Description
config.cors	Array[String]	The CORS allowlist. The T1C-API will automatically and dynamically update its own CORS allowlist when synchronizing with the DS API.
type	Enum	Multiple types of configuration exist, for the context config this will always be CONTEXT_CONFIG
versionId	String	Configurations are always tied to a version. This must match the id property of an existing version. This means that configurations need to be (re)created for every new version.
id	UUID	If the id property is specified, the request will perform an update operation instead of a create

Create Or Update File Digests Config

The file digests config contains a list of files and their MD5 digests. At startup, the T1C-API will verify that these files are unaltered and shut down if that is not the case. We recommend leaving it empty during testing.

Example

curl --location --request PUT 'http://localhost:8000/v3/configurations' \
    --header 'Authorization: Bearer eyJh...olw' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "config": {
            "files": []
        },
        "type": "FILE_DIGESTS",
        "versionId": "3.1.1"
    }'

Request

Property	Type	Description
config.files	Array[Object]	The CORS allowlist. The T1C-API will automatically and dynamically update its own CORS allowlist when synchronizing with the DS API.
config.files.path	String	The path of the file. OS agnostic, use / as a path separator
config.files.digest	String	The MD5 digest of the file
type	Enum	Multiple types of configuration exist, for the file digests this will always be FILE_DIGESTS
versionId	String	Configurations are always tied to a version. This must match the id property of an existing version. This means that configurations need to be (re)created for every new version.
id	UUID	If the id property is specified, the request will perform an update operation instead of a create

Create or Update SSL Keystore Config

The SSL keystore config contains the URI for the latest SSL keystore used by the T1C-API for it's local server. The T1C-API will check if it has the latest and unaltered SSL keystore at startup and replace it if necessary.

Example

curl --location --request PUT 'http://localhost:8000/v3/configurations' \
    --header 'Authorization: Bearer eyJh...olw' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "config": {
            "uri": "https://storage.googleapis.com/gcl-distro/ssl/t1c_ks.p12",
            "password": "test"
        },
        "type": "SSL_KEYSTORE",
        "versionId": "3.1.1"
    }'

Request

Property	Type	Description
config.uri	String	The URI for the SSL keystore. The URI can be of a file hosted online or of a file hosted on the server filesystem, e.g. https://domain/path/package or file:///path/package
config.password	String	The keystore password
type	Enum	Multiple types of configuration exist, for the SSL keystore this will always be SSL_KEYSTORE
versionId	String	Configurations are always tied to a version. This must match the id property of an existing version. This means that configurations need to be (re)created for every new version.
id	UUID	If the id property is specified, the request will perform an update operation instead of a create

Create Or Update Organization

An organization is an entity that groups labels together. It is required in order to create a label

Example

curl --location --request PUT 'http://localhost:8000/v3/organizations' \
    --header 'Authorization: Bearer eyJh...olw' \
    --header 'Content-Type: application/json' \
    --data-raw '{
            "name": "Trust1Team"
    }'

Request

Property	Type	Description
name	String	The display name of the organization. The name will be used to create the organization ID by setting it to lower case and removing any non-alphanumeric characters. While the display name can later be changed, the ID is immutable.
id	String	If the id property is specified, the request will perform an update operation instead of a create

Create Or Update Label

A label is analogous to an application in the DS API v2. In v3 a label is associated with an API key which applications can exchange for a temporary JSON web token that can be passed to the client. A label can be used by multiple applications, or a label can be created for each application.

Example

curl --location --request PUT 'http://localhost:8000/v3/labels' \
    --header 'Authorization: Bearer eyJh...olw' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "name": "rmc",
        "orgId": "trust1team"
        "apiKey": "a91753a8-e9ef-4852-b356-0283ec00fb05"
    }'

Request

Property	Type	Description
name	String	The display name of the label. The name will be used to create the label ID by setting it to lower case and removing any non-alphanumeric characters. While the display name can later be changed, the ID is immutable.
orgId	String	The organization ID; must match the id property of an existing organization.
apiKey	UUID	The API key for the label. If absent, a random UUID will be generated. The API key will automatically be registered on the Kong gateway. This key can be exchanged for an application token.
id	String	If the id property is specified, the request will perform an update operation instead of a create

Label IDs must be unique across all organizations as the T1C-API is not aware of any organizational context, only labels.