> For the complete documentation index, see [llms.txt](https://t1t.gitbook.io/t1c-distribution-service-v3-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://t1t.gitbook.io/t1c-distribution-service-v3-guide/v3.0.5/management.md). # 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](https://documenter.getpostman.com/view/371559/T1DpCxs1) 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 ```javascript 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 {% hint style="info" %} Note that the request is `x-www-form-urlencoded` {% endhint %} | 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 ```javascript { "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 ```bash 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](https://semver.org) 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 | {% hint style="warning" %} Label IDs must be unique across all organizations as the T1C-API is not aware of any organizational context, only labels. {% endhint %}