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 Parameter | Type | Description |
---|---|---|
applications | array | Describes a single application used for machine authentication |
next_page_token | string | Pagination token. Empty on first request. On subsequent requests copied from response. |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized. |
429 | Returned 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
Parameter | Type | Description |
---|---|---|
custom_claims | object | Custom claims to add to Application for use in access policies. |
display_name | string | Human-readable display name for this Application. |
roles | array |
{
"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 Parameter | Type | Description |
---|---|---|
client_id | string | Client ID for use in OIDC client credentials flow |
credentials | array | Describes a single time-limited secret |
custom_claims | object | Custom claims to add to Application for use in access policies. |
display_name | string | Human-readable display name for this Application. |
identity | string | Resource name for the application |
roles | array | |
tenant_id | string | Identity of the tenant owning this application |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
402 | Returned when the user’s quota of app registrations policies has been reached. |
403 | Returned when the user is not authorized. |
429 | Returned 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
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized. |
404 | Returned when the Application does not exist. |
429 | Returned 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 Parameter | Type | Description |
---|---|---|
client_id | string | Client ID for use in OIDC client credentials flow |
credentials | array | Describes a single time-limited secret |
custom_claims | object | Custom claims to add to Application for use in access policies. |
display_name | string | Human-readable display name for this Application. |
identity | string | Resource name for the application |
roles | array | |
tenant_id | string | Identity of the tenant owning this application |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized. |
404 | Returned when the Application does not exist. |
429 | Returned 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 Parameter | Type | Description |
---|---|---|
client_id | string | Client ID for use in OIDC client credentials flow |
credentials | array | Describes a single time-limited secret |
custom_claims | object | Custom claims to add to Application for use in access policies. |
display_name | string | Human-readable display name for this Application. |
identity | string | Resource name for the application |
roles | array | |
tenant_id | string | Identity of the tenant owning this application |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized. |
404 | Returned when the Application does not exist. |
429 | Returned 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 Parameter | Type | Description |
---|---|---|
client_id | string | Client ID for use in OIDC client credentials flow |
credentials | array | Describes a single time-limited secret |
custom_claims | object | Custom claims to add to Application for use in access policies. |
display_name | string | Human-readable display name for this Application. |
identity | string | Resource name for the application |
roles | array | |
tenant_id | string | Identity of the tenant owning this application |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized. |
404 | Returned when the Application does not exist. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |