App Lifecycle
User Disconnects Your Application
When a user disconnects your application from their account, you will no longer have access to their account.If you try to run a query against a user which is no longer connected to your app you will get the following error returned:
"User has disconnected this app from their account. Please delete this token"
It is possible to get notified when a user disconnects your application. Simply subscribe to the webhook: app_disconnect.
The businessId can be gathered from this webhook and compared against the business REST query to determine the exact IsOn24 account that is disconnecting from your application. The business_read query is available to all apps regardless of their scopes.
Forcefully Removing a Business
Service Unavailable
In some cases, our REST API service may be unavailable to your app. The following error message will appear:"Service temporarily unavailable"
When seeing this error message for prolonged durations, please contact support.
App Authorization (OAuth 2.0)
IsOn24 uses OAuth 2.0 to authorize an app's access to an IsOn24 user's account.OAuth 2.0 is an authorization framework. It provides authorization flows for web applications, desktop applications, and mobile devices. Some apps that use OAuth are Facebook, GitHub, and IsOn24.
OAuth 2.0 gives applications limited access to user accounts on an HTTP service. It delegates user authentication to the service that hosts the user's account. It then authorizes third-party apps to access the user's account.
OAuth 2.0 Roles
OAuth 2.0 defines four roles:
Resource Owner
Client
Resource Server
Authorization Server
The Resource Owner is a User
The resource owner is the IsOn24 admin user who authorizes your application to access their IsOn24 Account. The application is granted an access level corresponding to the scopes specified when the app was created.
The Client is an Application
The client is the app that you want to give access to the user’s IsOn24 account. Two things must happen before the client gains access:
The API must authenticate the user
The user must authorize the client
The Resource & Authorization Server is the API
The resource server hosts the protected user accounts. The authorization server verifies the user's identity and gives access tokens to the client. IsOn24 API fulfills both the resource and authorization server roles. We will refer to both of these roles combined as the Service or API role.
OAuth 2.0 Protocol Flow
The client requests authorization from the user.
The client receives an authorization grant from the authorization server.
The client requests an access token from the authorization server. It presents authentication of its own identity. The client also offers the authorization grant.
The authorization server issues an access token and a refresh token to the client.
The client requests resources from the resource server. It presents an access token for authentication.
The resource server serves the resource to the client.
If the access token expires, the client requests a new one. (See below refresh token flow)
Client ID and Client Secret
After you add your app, IsOn24 will give you a client identifier and a client secret. The client ID is a publicly exposed string. IsOn24 uses it to identify the application. It's also used to build authorization URLs that are presented to users.
IsOn24 uses the client secret to authenticate the identity of the application. You must keep it private between the application and the API.
Authorization Grant
In the Protocol Flow above, the first four steps cover obtaining an authorization grant and access token. IsOn24 implements the authorization code grant type.
Authorization Code Grant Type
The authorization code grant type is the most commonly used because it is optimized for server-side applications, where source code is not publicly exposed, and Client Secret confidentiality can be maintained. This is a redirection-based flow, which means that the application must be capable of interacting with the user-agent (i.e. the user's web browser) and receiving API authorization codes that are routed through the user-agent.
Authorization Code Flow
Step 1: Authorization Code Link
There are two ways for the Authorization Code Flow to begin. Either the IsOn24 admin user clicks on the Connect button from the app listing in IsOn24's Apps & Integrations page, or the admin user accesses an authorization link of the form:
https://exapi.IsOn24.com/exapi/oauth/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<CALLBACK_URL>&state=<STATE>
Here is an explanation of the authorization link components:
https://exapi.IsOn24.com/exapi/oauth/authorize is the API authorization endpoint
<CLIENT_ID> is where the app inserts its Client ID value that can be looked up from the Developer Center
This is how the API identifies the app
<CALLBACK_URL> is where IsOn24 will redirect the user immediately after the authorization code is granted
This is set by the developer in the Developer Center and must be URL encoded
<STATE> is a random string that the client has the option of generating so that it's possible to confirm that the same <STATE> string is returned with the granted authorization code (see Step 3)
When the authorization flow is started from IsOn24 Apps & Integrations page, there is no <STATE> string provided
Step 2: User Authorizes Application
When the user clicks the link above or clicks on the Connect button from IsOn24 Apps & Integrations page, they will be prompted to authorize the scopes of the app (as configured in the Developer Center) and they must click on the Allow Access button to proceed. If the user was not already logged in to their IsOn24 account in the current browser, then they will first be prompted to log in before seeing the screen below:
<TODO: authorization-screen-shot>
Step 3: Application Receives Authorization Code
If the user approves the access request, IsOn24 redirects the user-agent to your application's redirect URI, along with an authorization code. The redirect would look something like this (assuming the application is "yourapplication.com"):
https://yourapplication.com/callback?code=AUTHORIZATION_CODE&state=STATE
The client should check that the state parameter matches the value set in step 1 (if applicable).
If the user chooses to deny the access request, IsOn24 redirects the user-agent to your application's redirect URI with no additional parameters:
https://yourapplication.com/callback
Step 4: Application Requests Access Token
The application requests an access token from the API, by passing the authorization code along with authentication details, including the client secret, to the API token endpoint. Your application must use HTTPS, rather than HTTP, for this request. Here is an example POST request to IsOn24's token endpoint:
POST /exapi/oauth/token HTTP/1.1
Host: exapi.IsOn24.com
Content-Type: application/x-www-form-urlencoded
client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI
The result will look something like
{
"access_token": "eyJ0eXAiOiJmeubdiLCJhbGciOiJIUzI1NiJ9.eyJ...MH0.FAz4g5Q-Uugrs3d5juSB0PwHXDqsxcc-mRa4BW2lNJw",
"refresh_token": "5dd9be5ghj99b837cd3acaf2f59fb8fa"
}
This example does not contain a complete access token. The actual access token contains three components:
encodeBase64(header) + '.' +
encodeBase64(payload) + '.' +
encodeBase64(signature)
the payload may be of interest as it contains an exp value that encodes the token's expiry time. These are standard JWT tokens with signatures that are only verifiable by IsOn24.
Step 5: Application Receives Access Token
If the authorization is valid, the API will return a JSON response containing the "access_token" and a "refresh_token" to your app.
Your app is now authorized. It may use the access token to make REST queries against IsOn24 API. It is highly recommended to use the business query to collect the business name and id for easier tracking of which IsOn24 account the access token can be used for. This will also be important for tracking app disconnects in the future.
The access token can continue to be used until it expires (default expiration time is 60 minutes) or until the app is disconnected. The refresh token may be used anytime to request a new access token.
Refresh Token Flow
After an access token expires, using it to request the API will result in a 401 "Invalid Token Error". At this point, the refresh token can be used to request a fresh access token from the authorization server. Note: You do not need to wait for the access token to expire to use the refresh token. It may be used at any time.
There are a few cases where the refresh token may expire:
App is disconnected from the account via either:
Admin user disconnecting the app using the button on the App Marketplace listing
/businesses/<business-id> API getting used
Client Secret is rolled (note this cannot be done manually at this time)
The app connection is re-authorized after a scope change
After this process, the new Authorization Code can be used to request a new access token and refresh token
The user must start the OAuth flow again if both the access and refresh tokens expire. The app will prompt them to do so by sending them to IsOn24 and redirecting them back to the app's Callback URL.
Here is an example POST request to obtain a new access token via the refresh token:
POST /exapi/oauth/token HTTP/1.1
Host: exapi.IsOn24.com
Content-Type: application/x-www-form-urlencoded
client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
In return you will receive the access token and a refresh token. It is important to note that refresh tokens are configured to be long-lived for now. In the future, you can ensure they change every time a refresh token is used in the Refresh Token Flow.
Example Access Token Usage
Once the application has an access token, it may use the token to access the user's account via the API until the token expires or is revoked. Here is an example of an API request using curl. Note that it includes the access token:
curl -X GET -H "Authorization: Bearer ACCESS_TOKEN" "https://exapi.IsOn24.com/exapi/v2/businesses"
Assuming the access token is valid, the API will process the request according to its API specifications. The API will return a 401 "invalid_request" error if the access token is invalid.
Handling App Disconnects
Once an IsOn24 account has been connected to an app (and the Access and Refresh Tokens have been granted) there are typically two mechanisms for the account to disconnect the app:
Admin user on the account clicks the DISCONNECT button from the app listing page in IsOn24's App Marketplace
This will immediately invalidate the Access and Refresh Tokens for that account and will also trigger the app_disconnect webhook
It is highly recommended that all apps subscribe to this webhook
User disconnects the app/integration from another system outside of IsOn24
For this case we highly recommend using the /businesses/<business-id> REST API to notify IsOn24 that the account has been disconnected
The Access and Refresh Tokens will also be invalidated using this process