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

API to manage Application Registrations.

get  /archivist/iam/v1/applications/archivist/iam/v1/applications

List applications for the user's tenant

Description: Lists all applications for the user’s tenant

{
  "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=="
}
Response ParameterTypeDescription
applicationsarrayDescribes a single application used for machine authentication
next_page_tokenstringPagination token. Empty on first request. On subsequent requests copied from response.
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized.
429Returned when a user exceeds their subscription’s rate limit for requests.

post  /archivist/iam/v1/applications/archivist/iam/v1/applications

Registers a new application

Description: Registers a new application, generating a client ID and secret for use in machine authentication. Regenerates the client secret for the application matching the supplied UUID. The response will include the client secret, but it will not be possible to retrieve it afterwards.

null
ParameterTypeDescription
custom_claimsobjectCustom claims to add to Application for use in access policies.
display_namestringHuman-readable display name for this Application.
rolesarray

{
  "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"
}
Response ParameterTypeDescription
client_idstringClient ID for use in OIDC client credentials flow
credentialsarrayDescribes a single time-limited secret
custom_claimsobjectCustom claims to add to Application for use in access policies.
display_namestringHuman-readable display name for this Application.
identitystringResource name for the application
rolesarray
tenant_idstringIdentity of the tenant owning this application
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
402Returned when the user’s quota of app registrations policies has been reached.
403Returned when the user is not authorized.
429Returned when a user exceeds their subscription’s rate limit for requests.

delete  /archivist/iam/v1/applications/archivist/iam/v1/applications/{uuid}

Delete an application

Description: Deletes the application matching the supplied UUID

ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized.
404Returned when the Application does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.

get  /archivist/iam/v1/applications/archivist/iam/v1/applications/{uuid}

Fetch an application record

Description: Fetches the application record for the supplied UUID

{
  "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"
}
Response ParameterTypeDescription
client_idstringClient ID for use in OIDC client credentials flow
credentialsarrayDescribes a single time-limited secret
custom_claimsobjectCustom claims to add to Application for use in access policies.
display_namestringHuman-readable display name for this Application.
identitystringResource name for the application
rolesarray
tenant_idstringIdentity of the tenant owning this application
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized.
404Returned when the Application does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.

patch  /archivist/iam/v1/applications/archivist/iam/v1/applications/{uuid}

Update an existing application

Description: Allows updating of the display name and custom claims for an application

{
  "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"
}
Response ParameterTypeDescription
client_idstringClient ID for use in OIDC client credentials flow
credentialsarrayDescribes a single time-limited secret
custom_claimsobjectCustom claims to add to Application for use in access policies.
display_namestringHuman-readable display name for this Application.
identitystringResource name for the application
rolesarray
tenant_idstringIdentity of the tenant owning this application
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized.
404Returned when the Application does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.

post  /archivist/iam/v1/applications/archivist/iam/v1/applications/{uuid}:regenerate-secret

Regenerate the client secret for an application

Description: Regenerates the client secret for the application matching the supplied UUID. The response will include the client secret, but it will not be possible to retrieve it afterwards.

{
  "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"
}
Response ParameterTypeDescription
client_idstringClient ID for use in OIDC client credentials flow
credentialsarrayDescribes a single time-limited secret
custom_claimsobjectCustom claims to add to Application for use in access policies.
display_namestringHuman-readable display name for this Application.
identitystringResource name for the application
rolesarray
tenant_idstringIdentity of the tenant owning this application
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized.
404Returned when the Application does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.