App Management

Apps work against a single tenant. If you need to manage test and production environments separately you will need to create two apps. This is by design as Gentrack Cloud Integration Services always work against a single tenant to prevent data cross over. Once the app is created you can enable Gentrack Cloud Integration Services features you want that app to use.

App development lifecycle

When the app is created you will be issued app credentials. Most people will create 2-3 apps with each aligned to a specific tenant. For example, development, test, and production. From here you can use each of the respective credentials at each stage of your developer workflow.

1. Create your development app and build your prototype. You will start by exploring the using the development instance of your Core System. This will allow you to begin to exercise the APIs, including manipulating any of the data in the Core Systems.

2. Test the app you have built. Once you have your app working and unit tested it is time to move it to your test environment. Similar to how you progress changes around your Core System you will run more formal user acceptance testing. This is the time to also test swapping out the app credentials to ensure that your app still functions correctly before you move it to production.

3. Launch your app in production. When the app has been fully tested and is ready, it is time to move it to production. Swap out the credentials for your production app credentials, then deploy your app using the appropriate channel. We will monitor Gentrack Cloud Integration Services interactions with your core. If something goes wrong, we will be in touch to help you troubleshoot any issues.

Create a new app

1. Log into the Integration Portal.

2. Go to the Apps page and click Add App. Enter a unique name and select the tenant to be associated with this app. If your user is assigned a custom role (i.e., not an organisation administrator), you will only be able to create an app against a tenant that you have access to.

3. To retrieve credentials for the newly created app, follow the steps in the next section.

Note: you can also add an App from the Tenants page. Select the tenant from the list and click the click Add App. The tenant name will be defaulted to the selected tenant.

Manage app credentials

1. Log into the Integration Portal.

2. Go to the Apps page and click the app you want to manage to open the app details page.

3. Click on Overview tab. On this page, you will find the Client ID and masked Client Secret. These credentials will be used to request a JWT access token.

4. Not all apps require authentication, so you will not have a client secret when the app was first created. To generate a secret if you need it, click Regenerate Secret. If it is an existing app, this will invalidate the secret generated previously.

5. The secret will only be shown once after it has been generated so you will have to copy and keep it in your credentials manager. If you lose access to your app credentials, you will not be able to retrieve it again. You will have to generate a new secret to invalidate the previous one.

Request access token

Requests to Gentrack Cloud APIs are authenticated by requiring a JSON Web Token (JWT) in a Bearer authorization header. These tokens are obtained using the industry standard OAuth 2.0 flow.

For an app to be able to call Gentrack Cloud API it first needs to request a JWT access token from Gentrack Cloud Identity Services token endpoint which is https://uk.id.gentrackcloud.com/v1/token or https://au.id.gentrackcloud.com/v1/token depending on your organisation’s sovereignty region.

The token API uses HTTP Basic Auth where the app Client ID is the username and the app Client Secret is the password.

The following example shows how to request an access token with app credentials:

curl --location --request POST 'https://uk.id.gentrackcloud.com/v1/token' \
    --user appId-replaceme:appSecret-replaceme \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials'

The sample response is as follows:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjNiMzk2NTNiLWZhYjAtNGE0Ny1iMDczLTVjM2NjM2ExMT..AQ",
    "expires_in": 3600,
    "token_type": "Bearer"
}

You can then use the access token from the response to call Gentrack Cloud APIs. The following example shows calling a Universal Web API to retrieve app details:

curl -X GET \
    https://api-au.integration.gentrack.cloud/v1/apps/24453b1e-dace-457d-a1a9-1f837793a200 \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjNiMzk2NTNiLWZhYjAtNGE0Ny1iMDczLTVjM2NjM2ExMT..AQ'

The sample response is as follows:

{
    "id": "24453b1e-dace-457d-a1a9-1f837793a200",
    "name": "My Custom App",
    "tenantId": "61668309",
    "type": "Custom",
    "webhook": {
        "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu0RNLgzF/I/aj8Cg+yfa\nns4knSE8jUe4uUiWAs+68LYJM+fOHBJKTpAy2F1/WIcUka5pU6w2PDwXVHVGcs3q\nOZp7qoyse/4np2R5JF2jw7Hf5ks4+LWZG7/0bcunEepoiLmZwR3SBLDqy+gU7e/k\nfg60LG7ZgVEdnYZWZ6OaROQ7p4hwLCDEgQIp2Iz8wgejscExOEh/5YyaIE3dRLo7\nRnzBj+B8UZWlVSjxz0AfB32OawjSmC4VLzqHoQCsvSHuazttcX+c2wUsA0HRZB4F\n62qpxXrzk/gvcnbLdpYXMZgI7fOiyEpy5hcMlPLt+co0K1+b9zUDuFNrQi9UD/3a\nnQIDAQAB\n-----END PUBLIC KEY-----"
    },
    "updatedAt": "2021-07-14T01:44:55.292Z",
    "createdAt": "2021-06-02T01:52:13.329Z"
}

Tokens have a short lifespan and expire. Calling an API with an expired token will return 401 Unauthorized HTTP status code. To get a new token simply make another request to the token endpoint.

{
    "details": "Authorisation failure",
    "message": "Unauthorized",
    "requestId": "8012eecd-b18a-4d66-86cd-df05d557bb1f"
}

API Access Control Policy

App credentials allow your custom integrations to call Gentrack Cloud APIs. All of your Core System endpoints are accessible by default using these credentials. For increased security, you can limit the scope of each app by defining API policies. An API policy contains the routes that can be accessed and methods that are allowed for each route.

Create an API Policy for your organisation

1. Log into the Integration Portal as a user with administrator access.

2. Click API Policies under the Settings section.

3. Click Add Policy on the API Policies page and fill out all the fields:

   • Policy Name - Name of the policy to be created.
   • Route - An API route in your Core System that will be allowed access through this policy. API routes can contain wilcard characters (e.g. * will match any character) to allow you to define pattern matching criteria. Routes are matched after /v1/junifer or /v1/velocity. For example, an API route with pattern /accounts/* will match /v1/velocity/accounts/10001 and /v1/junifer/accounts/10002.
   • Methods - One or methods that will be allowed for the associated route.

4. Click Create Policy.

Assign API Policy to an app

1. Log into the Integration Portal.

2. Go to the Apps page and select the app that you want to assign a policy for.

3. On the Overview page, find the API Policy section and click Edit API Policy.

4. Select one or more policies and click Save.

Once a policy has been assigned to an app, only the routes and methods defined in the policy will be accessible. All other routes will return a Forbidden error.

To restore full access, follow the steps above and deselect all the policies assigned.

Simulate API Policy to an app

After one or more API policies are assigned to an App, you can use Simulate API Policy to test if the policies achieve the intended outcome of only allowing a certain set of API calls and denying others.

The simulation process checks the API request against the API policies in the same way GCIS receives a real API request. The difference is that no real API call will be made to the backend.

1. Log into the Integration Portal.

2. Go to the Apps page and select the app

3. On the Overview page, find the API Policy section and click Simulate API Policy.

4. Add API endpoints with both Route and Method and click Simulate. The route is the path to an API resource that you want to test against the policies, e.g., /accounts/12346/bills.

5. On success, simulation results will be displayed on a new page, which will confirm if every API endpoint in the list would be allowed or denied on the App. For an allowed API call, the policy that allows the call will also be displayed.

6. On the result page, click Back to return to the previous page where you can simulate again on a new set of API endpoints.

Subscribe to events

Set up event subscriptions for your apps to build workflows from the events published by your Core System. Refer to Events Reference for a list of supported events.

1. Log into the Developer Portal.

2. Go to the Apps page and click the app you want to manage to open the app details page.

3. Click on Event Subscriptions tab.

4. Click Edit Subsription on the Event Subscriptions page and fill out the form with the following:

   • URL of your End Point - Webhook URL for this app that will receive the published events. The Organisation Administrator MUST add the host name or IP address of the webhook URL to the Organisation Domain White List.
   • Events - The event list is grouped by namespace. Select one or more event types that you want this app to receive.

5. Click Save.