Setting up Xpand Portal API

To be able to access Xpand Portal data through Xpand Portal API, you must configure the following in Xpand Portal CMS:

  • API settings – These are general settings for Xpand Portal API.
  • API clients – You must add settings for each API client application that you want to grant access to portal data through API with JSON Web Token (JWT) authentication.
  • API settings for portal members – For each portal member that you want to grant access to portal data through Xpand Portal API, you must configure API-related settings in the portal member settings.

General API settings

To set up general API settings:

  1. In CMS, go to Media > Portal Settings > OAuth & SSO Settings.
  2. On the API settings tab, configure the settings as described below:
    • Enable API – Use this switch to enable or disable Xpand Portal API for all clients.
    • Allowed domains – Specifies the name of the domain that will be allowed to use Xpand Portal API. You can fill in this field with * to allow any domain name. If this setting is also specified for an API client, the API client's setting will be used instead.
    • Enable insecure connection – Enable this switch if you want to allow using an insecure connection to access API. With insecure connection, the HTTPS protocol is not required for API clients.
    • Xpand Portal realm name – Specifies the domain name of Xpand Portal, which may be necessary if the client application and the portal are both hosted on the same host so that unique settings could be provided for each app. 
    • Secret key – Specifies a symmetric key to sign a self-defined token. This key is generated automatically when you save these settings.
    • Token lifetime (min.) – Specifies the period in minutes that the authentication token (JWT) will be valid.
    • Refresh token after (min.) – Specifies after how many minutes the authentication token (JWT) will be refreshed. If this setting is also specified for an API client, the API client's setting will be used instead.
  3. Select Save.
  4. In CMS, select Settings, and then, on the Portal Settings tab, select Reload Application.

      Important

    You must reload application whenever you make changes in the Media section of CMS. Otherwise, your changes may not take effect.

API clients

To set up API clients that you want to grant access to portal data through API with JSON Web Token (JWT) authentication:

  1. In CMS, go to Media > Portal Settings > OAuth & SSO Settings.
  2. On the API clients tab, select the  icon to set up a new JWT client or select the  icon to edit an existing client configuration.
  3. Configure the settings as described below:
    1. Enabled – Specifies whether this API client is enabled. You can use this switch to temporarily block access to portal data through API for this client having the client settings preserved so that you could re-enable the client at a later time if necessary.
    2. Client application ID – Specifies the unique ID of the client application that will be able to use Xpand Portal API to get data from the portal or send data to the portal. This ID is used along with the secret key to grant access for the API client to portal data when OAuth 2.0 authorization is enabled. This ID can be alphanumeric text without spaces.
    3. Secret key – Specifies a secret key, which is used along with the client application ID to grant access for the API client to portal data when OAuth 2.0 authorization is enabled. Type the password for this API client that will be automatically transformed into a secret key after you save these settings.
    4. Enable OAuth 2.0 authorization – If you enable this switch, communication between the client and the portal will be secured by OAuth 2.0 authorization. In this case, in the API client, you will also need to authorize through OAuth 2.0 authentication to be able to get data from the portal or send data to the portal.
    5. Refresh token after (min.) – Specifies after how many minutes the OAuth 2.0 authentication token will be refreshed. FIll in this setting if you enabled the Enable OAuth 2.0 authorization switch.
    6. Allowed domains – Specifies the name of the domain that will be allowed to use Xpand Portal API with this API client. You can fill in this field with * to allow any domain name.
    7. Allow using multiple records synchronization methods - Specifies whether it's allowed for this client to use API methods that create, update, remove or retrieve multiple records. Enable this switch if you want to such API methods as Sync Get and Sync Store. Note that this setting can also be configured on the member level in the member settings.
  4. Repeat step 3 to configure more JWT clients if necessary.
  5. Select Save.
  6. In CMS, select Settings, and then, on the Portal Settings tab, select Reload Application.

      Important

    You must reload application whenever you make changes in the Media section of CMS. Otherwise, your changes may not take effect.

API settings for portal members 

To grant access to portal data through Xpand Portal API to a portal member:

  1. In CMS, go to Members> Members > All Members. and select a portal member for which you want to configure API settings.
  2. On the Settings tab, enable the Allow using API switch. This will generate an API secret key for this member, which will be displayed in the API secret key field.
  3. Copy the generated API secret key and provide it to the portal member so that they could use it in an API client.
  4. Enable the Allow using multiple records synchronization methods switch if you want to allow this member to use API methods that create, update, remove or retrieve multiple records. Enable this switch if you want to such API methods as Sync Get and Sync Store. Note that this setting can also be configured on the API client level in the API clients settings.