Appspace API: Application Integration

Disclaimer
API documentation can be accessed here. This API documentation site is intended for the internal use of approved participants only. This site is still in an Early Field Trial phase.

Introduction

The Appspace API allows you to integrate applications that can leverage a range of Appspace cloud and platform services. You can develop applications that integrate with Appspace channels, feeds, and much more using the Appspace API. Appspace API v3 is the latest iteration that has an expanded collection of methods across a wide variety of services. Documentation for all API methods can be accessed for each service, and is available online for developers to view.

Overview

In order to call the Appspace API, an application integration token is required. Before starting, your Appspace account must first be enabled to use API tokens. To get it enabled, please talk to the administrator of your Appspace account.

Once enabled, you can start creating API tokens that can be used to integrate with applications. This article outlines the steps needed to call the Appspace API using the application integration token. There are four parts to the process:

  1. Getting the Application Integration Token
  2. Getting the Access Token
  3. Calling the Appspace API
  4. Getting a new Access Token when it expires

Once you have created the application integration token, you can use that to call the Appspace API with an access token. These four parts are described in greater detail below.

Part 1: Getting the Application Integration Token

  1. To get the application integration token, you will need to sign in to the Appspace console and navigate to Admin > Integrations under the Appspace menu.
  2. Once you are in the Integrations page, navigate to the API Tokens tab and click Add to create a new token.
  3. In the API token creation modal pop-up, fill in the information for the token you are creating. The Client/Application and User fields are required, while the Description field is optional. The user that is selected to associate the token with needs to exist in the Appspace account. Click Create to finish the token creation process.
  4. You will now see your newly created token appear in the list. Click on the name of your newly created token to view its details.
  5. In the modal popup that shows your token details, copy the “SubjectId” and the “RefreshToken” values. These will be used in the next part to get the access token.

Part 2: Getting the Access Token

In order to get the access token, call the /api/v3/authorization/token endpoint with the “subjectId” and “refreshToken” values.

An example using curl is shown below:

curl --location --request POST 'https://{{appspaceUrl}}/api/v3/authorization/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"subjectType": "Application",
"subjectId": "{{subjectId}},
"grantType": "refreshToken",
"refreshToken": "{{refreshToken}}"
}'

A response format is shown below:

{
"accessToken": "{{jwtInBase64string}}",
"refreshToken": "{{refreshToken}},
"idToken": "{{jwtInBase64string}}",
"expiresIn": "{{accessTokenExpiryTimeInSeconds}}",
"refreshTokenExpiresIn": "{{refreshTokenExpiryTimeInSeconds}}",
}'

Copy the “accessToken” value that was generated in the response. This will be used in the next part to call the Appspace API. The access token is a JWT in base 64 string and the decoded payload has the “iat” which indicates the “issued at” time in UNIX timestamp format, and “exp”, which indicates the expiry time, also in UNIX timestamp format.

Part 3: Calling the Appspace API

In order to call the Appspace API, the “accessToken” needs to be inserted into the authorization header in the following format:

Authorization: Bearer {{accessToken}}

For example, in order to call the /api/v3/users endpoint, the following curl command can be used:

curl --location --request GET 'http://{{appspaceUrl}}/api/v3/channelDirectory \
--header 'Authorization: Bearer {{accessToken}}'

Part 4: Getting a New Access Token when it Expires

The access token has an expiry date, which is usually set to one hour. When the access token expires, a new one will need to be retrieved by calling the /api/v3/authorization/token endpoint again, as explained in Part 2.

Conclusion

By following the four part process above to create and renew a token, you have the ability to access the Appspace API for application integration. Simply ensure that the application you are developing will retrieve new access tokens at the stipulated time interval in order to continue calling the Appspace API during the application session.

Related Articles
Latest Articles