App Registrations API

App Registrations API Reference

Note: This page is primarily intended for developers who will be writing applications that will use DataTrails for provenance. If you are looking for a simple way to test our API you might prefer our Postman collection, the YAML runner or the Developers section of the web UI.

Additional YAML examples can be found in the articles in the Overview section.

App Registrations API Examples#

The App Registrations API enables you to create and manage application identities with access to your DataTrails Tenancy.

Note: App Registrations are called Custom Integrations in the DataTrail application UI.

It supports the OpenID Connect Client Credentials Flow, which means that for each application you register, a CLIENT_ID and SECRET are generated and returned.

These credentials are then used to request an access token from https://app.datatrails.ai/archivist/iam/v1/appidp/token, which is used for API authentication to DataTrails.

Each App Registration is created with Non-Administrator privileges by default.

To provide your credentials with access to the Assets and Events in your Tenancy, it is best practice to create an ABAC policy with specific, declared permissions.

If you wish to give your credentials Administrator privileges to access everything in your Tenancy, you would use the client-id as the subject and https://app.datatrails.ai/appidpv1 as the issuer in the Settings screen or by using the Administrators Endpoint in the Tenancies API.
This would be necessary if you want to carry out Tenancy administration via the API.

Note: For more information on App Registrations and access tokens, visit DataTrails Developer Patterns.

Creating an Application#

Create a JSON file with the parameters of your new application. Below is an example:

{
    "display_name": "TrafficLight101",
    "custom_claims": {
      "serial_number": "TL1000000101",
      "has_cyclist_light": "true"
    }
}

Once you have created your file, you can then submit it to the DataTrails API:

curl -X POST \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     -H "Content-Type: application/json" \
     -d "@/path/to/jsonfile" \
     https://app.datatrails.ai/archivist/iam/v1/applications

An example response is shown below.

The client secret must be taken note of at this point, as it will be redacted in any attempt to retrieve the application (shown as an empty string.)

{
    "identity": "applications/d1fb6c87-faa9-4d56-b2fd-a5b70a9af065",
    "display_name": "TrafficLight101",
    "client_id": "d1fb6c87-faa9-4d56-b2fd-a5b70a9af065",
    "tenant_id": "tenant/53e6bed7-6f4c-4a37-8c4f-cf889f2b1aa6",
    "credentials": [
        {
            "secret":"a0c09972b6ac912a4d67815fef88093c81a99b49977d35ecf6d162631aa29173",
            "valid_from": "2021-09-21T16:43:19Z",
            "valid_until": "2022-09-21T16:43:19Z"
        }
    ],
    "custom_claims": {
        "serial_number": "TL1000000101",
        "has_cyclist_light": "true"
    }
}

Caution: The expiry date refers to the secret only, any tokens generated with this secret will not automatically become invalid when the secret expires or is rotated. Each token has a TTL of 1 hour.

Authenticating with your Application#

Now that you’ve created an application, you get a token.

Replace ${CLIENT_ID} with the Application ID, and ${SECRET} with your secret from the App Registration.

curl https://app.datatrails.ai/archivist/iam/v1/appidp/token \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "client_id=${CLIENT_ID}" \
    --data-urlencode "client_secret=${SECRET}"

The token is found in the .access_token field and it is a base64 encoded JSON Web Token.

A common method to extract the token is to use jq, where $RESPONSE is the output your curl command:

TOKEN=$(echo -n $RESPONSE | jq -r .access_token)

You should then save the token to a local bearer_token file with 0600 permissions in the following format:

Authorization: Bearer $TOKEN

Where $TOKEN is the extracted token value.

You can then use this bearer token to interact with other DataTrails services.

Listing Applications#

All of the applications created for your DataTrails tenancy can be viewed using the following command.

curl -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/archivist/iam/v1/applications

Viewing Applications#

The following example shows how to view the details of a single application.

export IDENTITY="applications/d1fb6c87-faa9-4d56-b2fd-a5b70a9af065"

curl -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/archivist/iam/v1/${IDENTITY}

Updating Applications#

You may edit the display name and/or the custom claims of an application.

Create a JSON file containing the details you wish to update. Partial updating of applications is also supported. Below is an example:

{
    "custom_claims": {
      "has_cyclist_light": "false"
    }
}

Once you’ve created your file, submit it to the DataTrails API:

export IDENTITY="applications/d1fb6c87-faa9-4d56-b2fd-a5b70a9af065"

curl -X PATCH \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     -H "Content-Type: application/json" \
     -d "@/path/to/json"
     https://app.datatrails.ai/archivist/iam/v1/${IDENTITY}

Example response:

{
    "identity": "applications/d1fb6c87-faa9-4d56-b2fd-a5b70a9af065",
    "display_name": "TrafficLight101",
    "client_id": "d1fb6c87-faa9-4d56-b2fd-a5b70a9af065",
    "tenant_id": "tenant/53e6bed7-6f4c-4a37-8c4f-cf889f2b1aa6",
    "credentials": [
        {
            "secret": "",
            "valid_from": "2021-09-21T16:43:19Z",
            "valid_until": "2022-09-21T16:43:19Z"
        }
    ],
    "custom_claims": {
        "has_cyclist_light": "false"
    }
}

Regenerating Application Secrets#

It is possible to regenerate the secret for an existing application.

The expected response will be the same as for creation, but the credential entry will have been updated with a new secret, along with new expiry dates.

Once again, you must take note of the secret at this point, as it will not be recoverable.

export IDENTITY="applications/d1fb6c87-faa9-4d56-b2fd-a5b70a9af065"

curl -X POST \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/archivist/iam/v1/${IDENTITY}:regenerate-secret

Caution: The expiry date refers to the secret only, any tokens generated with this secret will not automatically become invalid when the secret expires or is rotated. Each token has a TTL of 1 hour.

Deleting Applications#

The following example shows how to delete an application.

export IDENTITY="applications/d1fb6c87-faa9-4d56-b2fd-a5b70a9af065"

curl -X DELETE \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/archivist/iam/v1/${IDENTITY}

App Registrations OpenAPI Docs#

{
  "applications": [
    {
      "client_id": "b222a12e-03d8-40b0-8d28-b851c2caadd0",
      "credentials": [
        {
          "secret": "",
          "valid_from": "2021-09-17T16:48:32Z",
          "valid_until": "2022-09-17T16:48:32Z"
        }
      ],
      "custom_claims": {
        "a": "b"
      },
      "display_name": "a",
      "identity": "applications/b222a12e-03d8-40b0-8d28-b851c2caadd0",
      "tenant_id": "tenant/fafb2d41-5237-45c7-9740-66d1635f549b"
    },
    {
      "client_id": "288e8cef-62fa-4eb0-9d36-ab01db27c182",
      "credentials": [
        {
          "secret": "",
          "valid_from": "2021-09-17T16:54:05Z",
          "valid_until": "2022-09-17T16:54:05Z"
        }
      ],
      "custom_claims": {
        "asf": "asbdf"
      },
      "display_name": "test",
      "identity": "applications/288e8cef-62fa-4eb0-9d36-ab01db27c182",
      "tenant_id": "tenant/fafb2d41-5237-45c7-9740-66d1635f549b"
    }
  ],
  "next_page_token": "eyJvcmlnX3JlcSI6eyJwYWdlX3NpemUiOjJ9LCJza2lwIjoyfQ=="
}

null

{
  "client_id": "ffaa0f30-a503-4de7-b085-d857ed34a7cd",
  "credentials": [
    {
      "secret": "2acc636e8439fa2ea1a613fe547a1d435b0b0ab3793f11751559d7431a3414eb",
      "valid_from": "2021-09-17T16:54:08Z",
      "valid_until": "2022-09-17T16:54:08Z"
    }
  ],
  "custom_claims": {
    "asf": "asbdf"
  },
  "display_name": "test",
  "identity": "applications/ffaa0f30-a503-4de7-b085-d857ed34a7cd",
  "tenant_id": "tenant/fafb2d41-5237-45c7-9740-66d1635f549b"
}

{
  "client_id": "ffaa0f30-a503-4de7-b085-d857ed34a7cd",
  "credentials": [
    {
      "secret": "2acc636e8439fa2ea1a613fe547a1d435b0b0ab3793f11751559d7431a3414eb",
      "valid_from": "2021-09-17T16:54:08Z",
      "valid_until": "2022-09-17T16:54:08Z"
    }
  ],
  "custom_claims": {
    "asf": "asbdf"
  },
  "display_name": "test",
  "identity": "applications/ffaa0f30-a503-4de7-b085-d857ed34a7cd",
  "tenant_id": "tenant/fafb2d41-5237-45c7-9740-66d1635f549b"
}

{
  "client_id": "ffaa0f30-a503-4de7-b085-d857ed34a7cd",
  "credentials": [
    {
      "secret": "2acc636e8439fa2ea1a613fe547a1d435b0b0ab3793f11751559d7431a3414eb",
      "valid_from": "2021-09-17T16:54:08Z",
      "valid_until": "2022-09-17T16:54:08Z"
    }
  ],
  "custom_claims": {
    "asf": "asbdf"
  },
  "display_name": "test",
  "identity": "applications/ffaa0f30-a503-4de7-b085-d857ed34a7cd",
  "tenant_id": "tenant/fafb2d41-5237-45c7-9740-66d1635f549b"
}

{
  "client_id": "ffaa0f30-a503-4de7-b085-d857ed34a7cd",
  "credentials": [
    {
      "secret": "2acc636e8439fa2ea1a613fe547a1d435b0b0ab3793f11751559d7431a3414eb",
      "valid_from": "2021-09-17T16:54:08Z",
      "valid_until": "2022-09-17T16:54:08Z"
    }
  ],
  "custom_claims": {
    "asf": "asbdf"
  },
  "display_name": "test",
  "identity": "applications/ffaa0f30-a503-4de7-b085-d857ed34a7cd",
  "tenant_id": "tenant/fafb2d41-5237-45c7-9740-66d1635f549b"
}