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 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.
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
ParameterTypeDescription
custom_claimsobjectCustom claims to add to Application for use in access policies.
display_namestringHuman-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 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
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.
defaultAn unexpected error response.

delete  /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.
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 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
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.
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"
}
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
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.
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 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
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.
defaultAn unexpected error response.

get  /archivist/iam/v1/applications:openapi

Get OpenAPI spec for AppRegistrations

Description: Get OpenAPI v2.0 spec for AppRegistrations

ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

get  /archivist/iam/v1/applications:openapi-ui

Get OpenAPI UI for AppRegistrations

Description: Get OpenAPI v2.0 UI for AppRegistrations

ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

Edit this page on GitHub