RKVST

Getting Access Tokens using a Custom Integration

Creating Access Tokens for RKVST

Non-interactive access to the RKVST platform is managed by creating Integrations with either a Custom Integration or one of our built-in Integrations. This is done using either the Settings Menu in the UI or by using the App Registrations API directly.

Note: App Registration is the previous name for an Integration.

Integrations have a CLIENT_ID and SECRET that can then be used to authenticate to RKVST IAM endpoints to issue a token (JWT) for accessing the rest of the RKVST API.

This authentication flow uses the industry-standard OIDC ‘Client Credentials’ Flow.

Creating a Custom Integration

Warning: You may only create and manage App Registrations with an Administrator level account.

When enabling non-interactive access to RKVST, you must create your first Integration in the RKVST UI.

Using the RKVST UI to create an Integration (First-Time Setup)

  1. As an Administrator, open the Settings interface.
Settings
  1. Navigate to the Integrations tab.
Navigate to Integrations
  1. Click the Custom box and the following form should appear:
Custom Integration Webform
  1. Enter any display name you’d like, then click Confirm.
You can optionally add any Custom Claims at this step. You must ensure they do not start with jit_ or use any of the well-known reserved claims. The Custom Claims can be used in an Attribute-Based Access Control (ABAC) policy to grant permissions.
Completed Web Registration
  1. You will then be presented with the CLIENT_ID and SECRET required by the archivist token endpoint.
Caution: You must take note of the SECRET at this point - it can not be viewed again later and you will have to generate a new one.
Record your Client ID and Secret
  1. Now that you have created your Custom Integration, follow the steps below to test generating a token and ensure you can access the RKVST API.

Note: By default, newly created Integrations will always have a Non-Administrator permission to the API, you must add the Integration as an Administrator to elevate it’s permissions.

You can add a Custom Integration as an Administrator using the Settings screen, where the issuer will be https://app.rkvst.io/appidpv1 and the subject will be your Integration’s CLIENT_ID.

Using the App Registrations API to create an Integration

Note: App Registration is the previous name for an Integration.

The following assumes you have at least one Custom Integration that has already been configured with Administrator permissions and that you are comfortable generating tokens and using the RKVST API.

If you do not yet have an Integration configured please follow the first-time setup guide to get started.

  1. Define your new Integration JSON and save it to a file locally.
{
    "display_name": "TrafficLight101",
    "custom_claims": {
      "serial_number": "TL1000000101",
      "has_cyclist_light": "true"
    }
}
  1. Generate a token using your pre-existing Custom Integration details.
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 as a base64 encoded JSON Web Token.

A common method to extract the token is to use jq, where $RESPONSE is the output of 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.

  1. Submit your new Application JSON to the App Registration API endpoint.
curl -X POST \
     -H "@$BEARER_TOKEN_FILE" \
     -H "Content-Type: application/json" \
     -d "@/path/to/jsonfile" \
     https://app.rkvst.io/archivist/iam/v1/applications

You should see a response with details about the Integration’s CLIENT_ID and SECRET:

{
    "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: You must take note of the SECRET at this point - it can not be viewed again later and you will have to generate a new one.
  1. You should now have a newly configured Integration and recorded its CLIENT_ID and SECRET. It can be used to generate a token and access the RKVST API.

For further details on using this API check out our App Registrations API Reference which contains more detailed usage examples and has the full OpenAPI Reference.

Getting a Token With Your Integration

Having completed the steps at Creating a Custom Integration, and having taken note of the CLIENT_ID and the SECRET, a token can be obtained with the following command.

Replace $CLIENT_ID with the Application ID, and $SECRET with your secret from the Integration.

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 returned from 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.

Testing Your Access

You can test access to the RKVST API using any of our standard calls. Doing a GET Assets is a very simple test.

For example:

curl -v -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/archivist/v2/assets

If successful, you should then see a list of the assets your Integration has access to in the tenancy. Note this may be an empty response if no assets are being shared with the user; this is an expected behaviour.

Otherwise, check the Assets OpenAPI Reference for more detailed information on the response codes you may expect if authentication fails and what they mean.

Troubleshooting Token Generation

The header and payload of the TOKEN may be examined with the following commands:

# Header
echo -n $TOKEN | cut -d '.' -f 1 | base64 -D

# Payload
echo -n $TOKEN | cut -d '.' -f 2 | base64 -D

This is useful when investigating if tokens contain the correct custom claims or tokens that may appear malformed.

Note: Decoding tokens with an online service exposes details about your RKVST until you delete the test secret.

Edit this page on GitHub

Containers as Assets →