Authenticating Appspace Cloud APIs

Appspace APIs allow for application integration that can leverage a wide range of Appspace cloud and platform services. You can develop applications that integrate with Appspace channels, feeds, and much more using Appspace APIs.

Appspace API v3 is the latest iteration that has an expanded collection of methods across a variety of services. Our latest API v3 library is available with Appspace 8.1-.ac.27 and later. Please select one of the following based on your public or private cloud instance to access your Appspace API v3 documentation:

Public cloud: https://api.cloud.appspace.com/api/v3/docs/
Private cloud: https://<yourcustomdomain>.cloud.appspace.com/api/v3/docs/

This article provides instructions to call the Appspace API to generate access tokens, which can then be used to call Appspace’s APIs to integrate with your applications:

Back to top

Get Application Integration Tokens

Important

Tokens must be created in the same public/private cloud instance as the API library.

Follow the instructions below to create an integration token for your API access:

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.
6. If you require an app token (e.g. for Microsoft Power Automate), enable the API Key option and copy the “apiKey” value.
7. Proceed to the Get Access Tokens section below.
Back to top

Get Access Tokens

Important
The access token has an expiry timeframe, which is usually set to one hour. When the access token expires, a new token must be retrieved by calling the /api/v3/authorization/token endpoint again, as per instructions below.

Follow the instructions below to create an access token:
1. 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}}",
}'
```
2. 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.
3. Proceed to the Call Appspace APIs section below.
Back to top

Call Appspace APIs

To call the Appspace API, insert the “accessToken” 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}}'
```
Example:
```
curl --location --request GET 'https://{{api.cloud.appspace.com/api/v3/docs}}/api/v3/channelDirectory \ 
--header 'Authorization: Bearer {{jwtInBase64string}}'
```
Back to top

Summary

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.