App Registrations API

App Registrations API Reference

App Registrations API Examples

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

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 can be used to request an access token from https://app.rkvst.io/archivist/iam/v1/appidp/token, used for application authentication to RKVST.

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 RKVST API:

curl -X POST \
     -H "@$BEARER_TOKEN_FILE" \
     -H "Content-Type: application/json" \
     -d "@/path/to/jsonfile" \
     https://app.rkvst.io/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 application registration.

curl https://app.rkvst.io/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 RKVST services.

Listing Applications

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

curl -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/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 "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/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 RKVST API:

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

curl -X PATCH \
     -H "@$BEARER_TOKEN_FILE" \
     -H "Content-Type: application/json" \
     -d "@/path/to/json"
     https://app.rkvst.io/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 "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/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 "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/archivist/iam/v1/${IDENTITY}

App Registrations OpenAPI Docs

get  /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
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized.
429Returned when the user has issued too many requests for their tenant’s subscription level.
defaultAn unexpected error response.

post  /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.

{
  "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
tenant_id string Identity of the tenant owning this application
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
402Returned when the user has created too many applications for their tenant’s subscription level.
403Returned when the user is not authorized.
429Returned when the user has issued too many requests for their tenant’s subscription level.
defaultAn unexpected error response.

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

Delete an application

Description: Deletes the application matching the supplied UUID

Responses Description
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 the user has issued too many requests for their tenant’s subscription level.
defaultAn unexpected error response.

get  /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
tenant_id string Identity of the tenant owning this application
Responses Description
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 the user has issued too many requests for their tenant’s subscription level.
defaultAn unexpected error response.

patch  /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"
}
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
tenant_id string Identity of the tenant owning this 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
tenant_id string Identity of the tenant owning this application
Responses Description
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 the user has issued too many requests for their tenant’s subscription level.
defaultAn unexpected error response.

post  /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
tenant_id string Identity of the tenant owning this application
Responses Description
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 the user has issued too many requests for their tenant’s subscription level.
defaultAn unexpected error response.

Edit this page on GitHub