App Assemblies
App assemblies appear in the catalog as top-level assemblies for app integrations:
The purpose of app assemblies is to obtain and validate any needed user credentials in order for trigger and action assemblies to make API calls on their behalf.
The most common patterns for obtaining user credentials are:
- No credentials needed
- The user needs to enter credentials like a username/password or API key
- The user needs to perform OAuth workflow
Sources of data like RSS news feeds need no authentication to access.
In this case, the app assembly just needs a single No Credentials Needed module:
The purpose of this module is to just allow the assembly to be saved as an app assembly and appear in the catalog as an app:
Some API's are accessed with credentials that must be entered by the user, like a username and password, or an API key.
The Pipedrive assembly is an example that can be copied and modified for these types of apps.
The first module presents a dialog window where the user can enter the needed API token:
This is what the dialog looks like when the assembly runs:
Next the assembly makes an API call using the provided token in order to validate it is correct:
A helpful link to the API documentation is provided that explains how the API expects to receive the API token.
If the API returns an error, a message is displayed:
Otherwise the API token is saved into the system's database via the Service Credentials – Save module:
Triggers and actions can retrieve the API token from the system's database using the Service Credentials – Get module.
Most major API's use the OAuth standard for authorizing user access to their API. APIANT currently supports standard implementations of both OAuth v1.0a and v2.0.
OAuth v1.0a and v2.0 integrations are done essentially the same. The only difference is that a different module is used in the app assembly depending upon which version the API uses.
The Asana app has a standard OAuth v2.0 integration:
All OAuth app assemblies need to safeguard the API keys provided by the API vendor when you register to access their API. See API Key Management.
It is also a good idea to protect the output data from the Utility - Keyvault Value modules, see Protecting output data.
Some OAuth v2.0 services require that the access token be refreshed.
They will provide a refresh token URL for this, which must be configured within the OAuth v2.0 Workflow module:
Follow their documentation to know which HTTP verb is needed (POST is used most often) and if the OAuth parameters need to be sent as HTTP body parameters or not.
The system is currently hardcoded to perform OAuth v2.0 token refreshes no faster than once every 15 minutes.
OAuth access tokens can expire due to these circumstances:
- The user chooses to revoke access by performing an action in the API provider's app.
- The OAuth v2.0 API provider requires that the access token be refreshed but the OAuth v2.0 Workflow module's settings for refreshing the token are not correct.
Whenever an access token becomes invalid, usually the API will return a 401 HTTP status code.
If an automation encounters a 401 HTTP status code when executing a trigger or action that uses OAuth, the system performs these steps:
- The user's connected account is disconnected by removing their credentials from the database
- All of the user's automations that use the connected account are turned off
