Pre-requisites

• The Developer Email has been linked to an Integration Application by the Integration Admin. 
  
  See: How Do I Create an Integrations Application and Invite a Developer to the Developer Portal? 

Process

1. The developer will receive an email with the subject “Developer Portal – Invitation" with instructions to complete the signup process:
   
   
2.  Check that the Email Address is correct, and click Send verification code:
   
   
3. Wait for the verification code email to arrive. Copy the code:
   
   
    
4. Paste the code in the Verification code field. Click Verify Code:
   
   
    
5. Enter your Full Name, Password, and Password confirmation. Click Create:
   
   
    
6. Click Log In to be redirected to the Developer Portal home page at one of these URLs:

• https://eu1.accountsiq.com/DevPortal
• https://eu2.accountsiq.com/DevPortal
• https://uk1.accountsiq.com/DevPortal
• https://us1.accountsiq.com/DevPortal

Pre-requisites

• The Developer has successfully completed the signup process.
• The Developer has received a One-Time Password (OTP) from the Integration Admin, to verify the Integration Application in the Portal (ideally by SMS or Phone call).

Process

1. On the Portal home page, the developer can see all the Applications available, including the Applications that need OTP Verification. Click on the OTP Verification Needed tile:
2. The developer will need to verify the applications with the OTP provided by the Integration Admin to access the details. Click on Verify, or anywhere in the row:
   
3. Enter the OTP received from the Integration Admin and click Validate:
   
4. The Integration Application Details and Entities Assigned to it are now accessible.

• Details tab: Credentials are hidden by default. Click Show Credentials to view them.
  
  
• Entities Assigned tab: This has column filtering and paging controls. 
  

Next Steps

At this point, the Developer is all set to start building their integration or adapter with AIQ.

The new WSDL endpoint has been built using the OAuth 2.0 protocol, Client Credentials Flow to validate API methods exposed to the public.

Authentication

The process of authentication will be performed using two API methods in conjunction: TokenGet() and TokenRefresh(): 

• The TokenGet() method receives your Application’s ClientId and ClientSecret (available in the Developer Portal) and returns an AccessToken and a RefreshToken.
  • AccessToken: This is valid for 60 minutes and must be passed on the SOAP Header of any subsequent API call. It will also have the built-in Permissions assigned to the Application by the Integration Admin; this means you will only be able to call certain API methods based on these permissions assigned to it.
  • RefreshToken: This is valid for 90 days and, once your AccessToken has expired, this method must be used to acquire a new pair of AccessToken and RefreshToken by calling the TokenRefresh method mentioned above. 
• The TokenRefresh() method also receives your Application’s ClientId, ClientSecret, and RefreshToken from your previous call, and it returns a new pair of AccessToken and RefreshToken with the same lifetime.

Authentication Recommendations

It is strongly recommended that in your workflow you do not call TokenGet() more than once, unless you have misplaced your RefreshToken and cannot exchange it, or you are not getting back a new one from us or it has expired.

Otherwise, after you got your first pair of AccessToken and Refresh Token, just call keep calling TokenRefresh() method to obtain new tokens.

SOAP Header

Once you’ve your AccessToken and RefreshToken sorted, all API calls must include a SOAP Header within the envelope and must be named AiqSoapHeader with the attribute:

 xmlns="http://www.visorsoftware.com/visor/accountsiq/dashboard/Integration/"

Sample SOAP Header:

<Header>
       <AiqSoapHeader xmlns="http://www.visorsoftware.com/visor/accountsiq/dashboard/Integration/">
           <Entity></Entity>
           <AccessToken></AccessToken>
       </AiqSoapHeader>
</Header>

The AIQ SOAP Header section needs to contain two properties:

• Entity ID you are trying to access. The Application linked to the AccessToken you are passing was granted access to different entities within your Group during setup (visible in the Developer Portal), hence it can only access these entities. If you are passing an invalid entity, an error will be returned.
• AccessToken valid for an Application, with the Permissions built-in (Read&Write or Read only).,

Pre-requisites:

• Access to the Developer Portal. 
• Have a verified Integration Application to get its Client Id and Client Secret

Process

To call this method successfully you must provide the ClientId and ClientSecret. It returns an AccessToken which is valid for 60 minutes, and a RefreshToken that lasts 3 months.

The AccessToken will only be valid to access Entities assigned to the Integration Application it was exchanged for, and with the Scopes/Permissions it was granted during setup. All this information is available in the Developer Portal.

Sample Request and Response

Request:

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <Body>
       <TokenGet xmlns="http://www.visorsoftware.com/visor/accountsiq/dashboard/Integration/">
           <clientId>88bd88ed-06ef-ed11-b23f-0022489a770e</clientId>
           <clientSecret>qwerty123456</clientSecret>
       </TokenGet>
   </Body>
</Envelope>

Response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
       <TokenGetResponse xmlns="http://www.visorsoftware.com/visor/accountsiq/dashboard/Integration/">
           <TokenGetResult>
<Result>
<AccessToken>eyJhbGciOiJSUzI1NiIsImtpZCI6Ilg1ZVhrNHh5b2pORnVtMWtsMll0djhkbE5QNC1jNTdkTzZRR1RWQndhTmsiLCJ0eXAiOiJKV1QifQ.eyJpZHAiOiJMb2NhbEFjY291bnQiLCJzdWIiOiI3MjE4ZTc5ZC00MDRhLTRjZTMtOTA1NS1iYThkYTE2MmVjOWYiLCJleHRlbnNpb25fQWlxQXBwSWQiOiI1NmUzYzI4Mi1lNDA5LWVlMTEtYjI2ZC0wMDIyNDg5YTc3MGUiLCJ0ZnAiOiJCMkNfMV9BSVFfU3RhbmRhcmQiLCJzY3AiOiJXcml0ZSBSZWFkIiwiYXpwIjoiNTZkMDZlNGEtMTgxZi00NTg2LWFiZDctN2UwMWY2ZGUwMGQxIiwidmVyIjoiMS4wIiwiaWF0IjoxNjg2NjU4NzkzLCJhdWQiOiIwNmQ1OGM0Ni1iYzg1LTQ2NDctYWUzMC0yMWQ1ZDUzNTM4OGMiLCJleHAiOjE2ODY2NjIzOTMsImlzcyI6Imh0dHBzOi8vYWlxc3RzdGVzdC5iMmNsb2dpbi5jb20vNGU4MzdkMjgtMzU0OS00OTQwLTkyYzctYmZlMmJkNGUyYjUyL3YyLjAvIiwibmJmIjoxNjg2NjU4NzkzfQ.PPVSe8F_wZG_lJvJXMC7r-DcQk-li0xwuiwN7YgAKK5zDpl7ZxLet0t95jRTJfNiZcxa3VznWfJOI_FoThr7fRpmauzHkfT3nR6yb9vZVofJojTr76chIe-mAfNz5zo5Lr5kX1_KJoe_0lxxrwHvUdXIVJgNK9n6FfWJIkc6O_4u6NzDNfF6bYPUnCm7FLqOdF3MXnKDN7PQOlLXqdqb9THwJeeB3fDs2mctRB9jevFwF2YYwG1nkhvyanMbbpeKQJaTXKQvNxFDYXWBtR_ri_OG1klwQWzADw4HHCU9vdszDKK-x0Sa9CKzoXwR2umwL1cdarEmydQyHSO--lVfzg</AccessToken>              <RefreshToken>eyJraWQiOiJjcGltY29yZV8wOTI1MjAxNSIsInZlciI6IjEuMCIsInppcCI6IkRlZmxhdGUiLCJzZXIiOiIxLjAifQ..CLvTiV3Yqxa50CiZ.GnaeGtXfHtNDFON4ApFue6NZpFp7qUym3kuwzFkorp9sBMS5MhPB0MB7ossm5q9NwqpLX0ACbSt_sXG43bvvAe0bpoaUv897ZBM_p2qUdV9kA5uAy8koqKVokP-X1oosEiJJ5ERaYfNQyEsHknw84WuMraf9s3MfdMQxqKE1YwmMUQthUfUaGFdWRh1UvPZoCIgiM2yX0jr8uk9iUCrtigfoCLjnSYUH5npGAf1H5eO_GYh9I7mzFF3hrNQjKSlVKTdG8w9VibNE7RL-2EDGtg37ZfkSBpdUDS5Tx2JbC2LsvKThqG0w1J7NXaFQuVlVTKwuOIOh_f4CtiWUe1Ea8eFQk9uNJA0SthiluJE0cnhu8MRhkQsrjYMaOq68prL5d69vgWgmX6IdeUMSqU4wktN67NOJfWxLxSxcwOJXsZhbybUg_Z4a0hR0VBnbISQfTan4U5Vvz8i4xoJqgkKzetzzmRpIEOdFPsKlorLMZxP6yaF2oRVoYMlyBYO-JY7cmieNC564mCUlG7Op-y00Ow5gybrYXianopdlZGlCnsmxTlDByGcSeE6T7STFOElEFHnor3DKBSw44etSSyN4FqjP6VOYffCyxU2kCr9Efjqi6WRbu88mEqn4-heMJFWbLY-y5gUDgP07Fk5pCij9-3HMR25hgQpJHbM_DXlAJQ9H4WJ23WOkw6erZxn9m9rx2T9EvBVKop_lm-LK6kBWqQRLPMA2JSD515mwytkEn8m5rxvwwswDVaIIPltYPVc.X0SgfqX0J6wp_Qf5d1Hs5g</RefreshToken>
                </Result>
               <Status>Success</Status>
               <ErrorCode>SUCCESS</ErrorCode>
           </TokenGetResult>
       </TokenGetResponse>
   </soap:Body>
</soap:Envelope>

Possible Error Codes and Throttling

OAUTH_INTEGRATION_APPS_CLIENTID_IS_NULL_OR_EMPTY
OAUTH_INTEGRATION_APPS_CLIENTSECRET_IS_NULL_OR_EMPTY
OAUTH_INTEGRATION_APPS_UNABLE_TO_PARSE_GUID_TO_STRING
OAUTH_INTEGRATION_APPS_APP_NOT_FOUND
OAUTH_INTEGRATION_APPS_APPLICATION_IS_REVOKED
UNKNOWN (contact integrations squad)

Throttling:

You can only call TokenGet() 10 times per hour. It will count how many calls you have made in the last 60 minutes. If it is more than 10 you will not be able to make further calls.

If you make more than one call per second, you’ll have to wait for a one-minute cooldown.

OAUTH_INTEGRATION_APPS_TOO_MANY_API_CALLS
OAUTH_INTEGRATION_APPS_RATE_LIMIT_REACHED

Prerequisites: 

• Access to the Developer Portal. 
• Have a verified Integration Application to get its ClientId and ClientSecret
• Own a valid RefreshToken from a previous call to TokenGet().

Process

To call this method successfully you must provide your ClientID, ClientSecret, and RefreshToken from your previous TokenGet() call. It returns a new pair of AccessToken and RefreshToken with the same lifetime.

If your RefreshToken has expired, you will need to call TokenGet() again.

Sample Request and Response

Request:

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <Body>
       <TokenRefresh xmlns="http://www.visorsoftware.com/visor/accountsiq/dashboard/Integration/">
<clientId>56e3c282-e409-ee11-b26d-0022489a770e</clientId>
<clientSecret>qwerty123456y</clientSecret> <refreshToken>eyJraWQiOiJjcGltY29yZV8wOTI1MjAxNSIsInZlciI6IjEuMCIsInppcCI6IkRlZmxhdGUiLCJzZXIiOiIxLjAifQ..CLvTiV3Yqxa50CiZ.GnaeGtXfHtNDFON4ApFue6NZpFp7qUym3kuwzFkorp9sBMS5MhPB0MB7ossm5q9NwqpLX0ACbSt_sXG43bvvAe0bpoaUv897ZBM_p2qUdV9kA5uAy8koqKVokP-X1oosEiJJ5ERaYfNQyEsHknw84WuMraf9s3MfdMQxqKE1YwmMUQthUfUaGFdWRh1UvPZoCIgiM2yX0jr8uk9iUCrtigfoCLjnSYUH5npGAf1H5eO_GYh9I7mzFF3hrNQjKSlVKTdG8w9VibNE7RL-2EDGtg37ZfkSBpdUDS5Tx2JbC2LsvKThqG0w1J7NXaFQuVlVTKwuOIOh_f4CtiWUe1Ea8eFQk9uNJA0SthiluJE0cnhu8MRhkQsrjYMaOq68prL5d69vgWgmX6IdeUMSqU4wktN67NOJfWxLxSxcwOJXsZhbybUg_Z4a0hR0VBnbISQfTan4U5Vvz8i4xoJqgkKzetzzmRpIEOdFPsKlorLMZxP6yaF2oRVoYMlyBYO-JY7cmieNC564mCUlG7Op-y00Ow5gybrYXianopdlZGlCnsmxTlDByGcSeE6T7STFOElEFHnor3DKBSw44etSSyN4FqjP6VOYffCyxU2kCr9Efjqi6WRbu88mEqn4-heMJFWbLY-y5gUDgP07Fk5pCij9-3HMR25hgQpJHbM_DXlAJQ9H4WJ23WOkw6erZxn9m9rx2T9EvBVKop_lm-LK6kBWqQRLPMA2JSD515mwytkEn8m5rxvwwswDVaIIPltYPVc.X0SgfqX0J6wp_Qf5d1Hs5g
</refreshToken>
       </TokenRefresh>
   </Body>
</Envelope>

Response:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
<TokenRefreshResponse              xmlns="http://www.visorsoftware.com/visor/accountsiq/dashboard/Integration/">
<TokenRefreshResult>
<Result>
 <AccessToken>eyJhbGciOiJSUzI1NiIsImtpZCI6Ilg1ZVhrNHh5b2pORnVtMWtsMll0djhkbE5QNC1jNTdkTzZRR1RWQndhTmsiLCJ0eXAiOiJKV1QifQ.eyJpZHAiOiJMb2NhbEFjY291bnQiLCJzdWIiOiI2YmE4M2I4NS1jYWU4LTQwMWUtYWIyZC1lM2UwN2VkZGQxNzMiLCJleHRlbnNpb25fQWlxQXBwSWQiOiJhNzE1YWM3Zi1jNWU1LWVkMTEtODZmOC1lNGI5N2FlZjAzN2EiLCJ0ZnAiOiJCMkNfMV9BSVFfU3RhbmRhcmQiLCJzY3AiOiJXcml0ZSBSZWFkIiwiYXpwIjoiYTJkNDVlZTktMzg0MC00MjI1LWI2MjUtZDcyMmU4ZDg3Mzc3IiwidmVyIjoiMS4wIiwiaWF0IjoxNjg2NjY3MjY2LCJhdWQiOiIwNmQ1OGM0Ni1iYzg1LTQ2NDctYWUzMC0yMWQ1ZDUzNTM4OGMiLCJleHAiOjE2ODY2NzA4NjYsImlzcyI6Imh0dHBzOi8vYWlxc3RzdGVzdC5iMmNsb2dpbi5jb20vNGU4MzdkMjgtMzU0OS00OTQwLTkyYzctYmZlMmJkNGUyYjUyL3YyLjAvIiwibmJmIjoxNjg2NjY3MjY2fQ.m8px1lOM3o71FG0x3tlMZ7GeJYZlYR7ffhCpsnhT-K4A9M0JVhtzKZ5bv33HAVhQScs9Q4k5pFYPtIB97PTU5G5Ld6AYTto2p1TbMWDKx2OgvAywzbuh6cYTHeXvg_7QaBI_kv27kHy62DT4qZa6fgT0zMOz-xjLuWFSoKOkVJilkATcLxO6NL3n18fmvz9o8zke86YtcjybwKkkuzpKsrgEbWcZx7EqEFnuJ1J27xaaRqOy7VEQCGBK60P9kep5s7JCVCEvWJwgMH1_vW6PGom5_8MBNjz3Fr59UeNRUn0pgF-vvsOY4wIwWBjJv3eCkw2-jEr9TLwLclPYHpkPEg</AccessToken>               <RefreshToken>eyJraWQiOiJjcGltY29yZV8wOTI1MjAxNSIsInZlciI6IjEuMCIsInppcCI6IkRlZmxhdGUiLCJzZXIiOiIxLjAifQ..e2c7JsMPEY7dHJSK.c4wpQHIUD4SRNxZMQVAcf8d4tM3jDDv9KLvXjrsbpTnNEd9ACXY_Kvposgdp-SfEHslix2sMRPc4d6HvvRmk-w2mx3jpzrb9wqbF-qcwvAG1youWeIV7OnaBBGAuUe1h3b49sTs_JvqJC6uJ9pwBNDPovV6NU6tFmLUYvjsatrlhARBsf0e5lrlviqgb1CD9uRuASLDy5k_tELy1aNkUWITZWHBYbAUamHNHqusFJcbu9RQukPoHKu0XMLQpKD1wWBql21iUNBf_BCTJHUlRDx1hyElHATDCxZpvAqzDTIaJ_p6SHWNesgVUzl6ZH3_QJJCKfBZzmD6Pz-l5KBbB0IkUb-HMWPc0oHdAMgpnQjN-Li-OgEJlgG9yFQhTHGb4TcWyxwVKCie6My9l0C0bR0c_hX14Mlpu5ipHaWWvxTLTnQhsNT8n6I8TFLRhdwSTJy5P0z1Yw_GEy0_pXVZs6UguzixUmRas8dFVcVKALCJ9DHF745QPaA6DfzDU6EGDLX21dEW9MtycZEaBSoHsYAj29SfCOUJ3lSa2CmXtm4_BBTDt-5r5UegvPlwrp23ry55IAes_B-_8cyE40PS6iZ1Vr1YJqpaj22h7UOtRUgE4RhuhrY0bgKWPGv2vF18_IZnTzWW-nOsIenE3WEilX6R5b_KLaiEMPWjl5iMmA8_iV9A_E9Md1xQQyffEJT60NSew8KLqtj1siZjLgT-PrG9-46W9W-Vwe43hifL9hJ0kYUJdzCdoEa1CYF_ots0c4ng.4Z_maCsJjM79ldmlUxDVrQ</RefreshToken>
                </Result>
               <Status>Success</Status>
               <ErrorCode>SUCCESS</ErrorCode>
           </TokenRefreshResult>
       </TokenRefreshResponse>
   </soap:Body>
</soap: Envelope>

Possible Error Codes and Throttling

OAUTH_INTEGRATION_APPS_CLIENTID_IS_NULL_OR_EMPTY
OAUTH_INTEGRATION_APPS_CLIENTSECRET_IS_NULL_OR_EMPTY
OAUTH_INTEGRATION_APPS_UNABLE_TO_PARSE_GUID_TO_STRING
OAUTH_INTEGRATION_APPS_APP_NOT_FOUND
OAUTH_INTEGRATION_APPS_APPLICATION_IS_REVOKED
UNKNOWN (contact integrations squad)

Throttling: 

You can only call TokenRefresh() 100 times per hour. It will count how many calls you have made in the last 60 minutes. If it is more than 100 you will not be able to make further calls.

If you make more than one call per second, you’ll have to wait for a one-minute cooldown.

OAUTH_INTEGRATION_APPS_TOO_MANY_API_CALLS
OAUTH_INTEGRATION_APPS_RATE_LIMIT_REACHE

The rest of the SOAP API methods are the same as in Integration_1_1, to provide backward compatibility.

GetCurrencyList() Sample Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <Header>
       <AiqSoapHeader xmlns="http://www.visorsoftware.com/visor/accountsiq/dashboard/Integration/">
<Entity>AIQ1234</Entity>
<AccessToken> eyJhbGciOiJSUzI1NiIsImtpZCI6Ilg1ZVhrNHh5b2pORnVtMWtsMll0djhkbE5QNC1jNTdkTzZRR1RWQndhTmsiLCJ0eXAiOiJKV1QifQ.eyJpZHAiOiJMb2NhbEFjY291bnQiLCJzdWIiOiI2YmE4M2I4NS1jYWU4LTQwMWUtYWIyZC1lM2UwN2VkZGQxNzMiLCJleHRlbnNpb25fQWlxQXBwSWQiOiJhNzE1YWM3Zi1jNWU1LWVkMTEtODZmOC1lNGI5N2FlZjAzN2EiLCJ0ZnAiOiJCMkNfMV9BSVFfU3RhbmRhcmQiLCJzY3AiOiJXcml0ZSBSZWFkIiwiYXpwIjoiYTJkNDVlZTktMzg0MC00MjI1LWI2MjUtZDcyMmU4ZDg3Mzc3IiwidmVyIjoiMS4wIiwiaWF0IjoxNjg2NjY3MjY2LCJhdWQiOiIwNmQ1OGM0Ni1iYzg1LTQ2NDctYWUzMC0yMWQ1ZDUzNTM4OGMiLCJleHAiOjE2ODY2NzA4NjYsImlzcyI6Imh0dHBzOi8vYWlxc3RzdGVzdC5iMmNsb2dpbi5jb20vNGU4MzdkMjgtMzU0OS00OTQwLTkyYzctYmZlMmJkNGUyYjUyL3YyLjAvIiwibmJmIjoxNjg2NjY3MjY2fQ.m8px1lOM3o71FG0x3tlMZ7GeJYZlYR7ffhCpsnhT-K4A9M0JVhtzKZ5bv33HAVhQScs9Q4k5pFYPtIB97PTU5G5Ld6AYTto2p1TbMWDKx2OgvAywzbuh6cYTHeXvg_7QaBI_kv27kHy62DT4qZa6fgT0zMOz-xjLuWFSoKOkVJilkATcLxO6NL3n18fmvz9o8zke86YtcjybwKkkuzpKsrgEbWcZx7EqEFnuJ1J27xaaRqOy7VEQCGBK60P9kep5s7JCVCEvWJwgMH1_vW6PGom5_8MBNjz3Fr59UeNRUn0pgF-vvsOY4wIwWBjJv3eCkw2-jEr9TLwLclPYHpkPEg </AccessToken>
</AiqSoapHeader>
   </Header>
   <Body>
       <GetCurrencyList xmlns="http://www.visorsoftware.com/visor/accountsiq/dashboard/Integration/">
           <token></token>
       </GetCurrencyList>
   </Body>
</Envelope>

Possible Error Codes Returned

OAUTH_INTEGRATION_APPS_AIQ_SOAP_HEADER_MISMATCH
OAUTH_INTEGRATION_APPS_TOKEN_EXPIRED (AccessToken has expired. Use RefreshToken to get a new AccessToken)
OAUTH_INTEGRATION_APPS_TOKEN_NOT_PROVIDED_IN_AUTHORIZATION_HEADER
OAUTH_INTEGRATION_APPS_NO_ENTITY_PROVIDED_IN_HEADER
OAUTH_INTEGRATION_APPS_APP_NOT_FOUND
OAUTH_INTEGRATION_APPS_APPLICATION_IS_REVOKED
OAUTH_INTEGRATION_APPS_ERROR_VALIDATING_TOKEN
OAUTH_INTEGRATION_APPS_TOKEN_DOES_NOT_HAVE_PERMISSION (entity being accessed is not assigned or insufficient permissions/scopes selected)
UNKNOWN (contact integrations squad)

If you have an existing working integration, adapter, or workflow with AIQ, with some simple steps you could migrate it to use our new Integration Applications platform and its OAuth 2.0 protocol, Client Credentials Flow implementation to validate the API methods accessing the protected resources.

It is important to mention that all the API methods available are the same and work in almost the exact same way as before. The main two differences are:

• Each API method must now include a SOAP Header envelope.
• The token property in the SOAP Body can be removed or left empty, as it will be ignored completely.

New WSDL Endpoint

There is a new WSDL endpoint you will need to reference. The beginning of the URL is the same, but it ends with Integration_2_0 instead of Integration_1_1. 

New Login Method

In this new Integration_2_0 endpoint, the old-fashioned Login method has been removed entirely, and the Token that you used to get back from it and needed to subsequently include in the body of any further API call can now be safely ignored. This means the UserKey and PartnerKey are out of the picture as well, and now everything can be done and managed through two user interfaces:

• AccountsIQ: The Integration Admin creates and manages Integration Applications and invites a Developer to the Portal by their email. 
• Developer Portal: The Developer linked to an Integration Application can get the details and credentials to access the protected API method.

Authentication Changes

For Integration_2_0 the new way of authentication will be performed using two new API methods in conjunction: TokenGet() and TokenRefresh(), which in the background are implementations of the OAuth 2.0, Client Credentials Flow. 

• The TokenGet() method receives your Application’s ClientId and ClientSecret (available in the Developer Portal) and returns an AccessToken and a RefreshToke
  • AccessToken: This is valid for 60 minutes (compared to the old Token which had a lifespan of 20 minutes only) and must be passed on the SOAP Header of any subsequent API call. It will also have the built-in Permissions assigned to the Application by the Integration Admin; this means you will only be able to call certain API methods based on these permissions assigned to it.
  • RefreshToken: is valid for 90 days and, once your AccessToken has expired, this method must be used to acquire a new pair of AccessToken and RefreshToken by calling the TokenRefresh method mentioned above. 
• The TokenRefresh() method also receives your Application’s ClientId, ClientSecret, and RefreshToken from your previous call, and it returns a new pair of AccessToken and RefreshToken with the same lifetime.

Authentication Recommendations

It is strongly recommended that in your workflow you do not call TokenGet() more than once, unless you have misplaced your RefreshToken and cannot exchange it, or you are not getting back a new one from us or it has expired.

Once you got your first pair of Access Token and Refresh Token, you should make further calls to TokenRefresh() method to obtain new tokens.

SOAP Header Changes

As mentioned before, now every API call must include a SOAP Header within the envelope and must be named AiqSoapHeader.

<Header>
        <AiqSoapHeader xmlns="http://www.visorsoftware.com/visor/accountsiq/dashboard/Integration/">
           <Entity></Entity>
           <AccessToken></AccessToken>
       </AiqSoapHeader>
</Header>

The AiqSoapHeader section needs to contain two properties:

• AccessToken valid for an Application, with the Permissions built-in (Read&Write or Read only)
• Entity ID you are trying to access. The Application linked to the AccessToken you are passing has been granted access to different entities within your Group during setup, hence it can only access these entities. If you are passing an invalid entity, an error will be returned.

Soap Body Token Property Change

Lastly, for backward compatibility and to make things a bit easier for existing integrators, the token property will still be present by default in the SOAP body of the API methods, but it will be ignored as we will not be using it anymore to authenticate the request. If you would like to delete it, this is fine as well.

Key Takeaways for Migration

• It is no longer needed to have a PartnerKey and UserKey to use our SOAP API. Hence, there is no need to have an ad-hoc system User linked to your integration.
• No need to call the Login method to get a Token (valid for 20 minutes) and include it in the body of any further API call.
• New endpoint named Integration_2_0, which implements OAuth 2.0 Client Credentials Flow through TokenGet() and TokenRefresh() methods.
• Every API request must now include a SOAP Header, named AiqSoapHeader, where a valid AccessToken (valid for 60 minutes) and Entity being accessed must be provided.
• New Developer Portal to manage everything in relation to the Integration Applications linked to a Developer Email, including ClientID and ClientSecret, Permissions, Assigned Entities, etc.
• In Integration_2_0, one Integration Application could potentially have permissions to access all Entities within a Group as a Service User, invisible in the system. On the other hand, in Integration_1_1 a Token is only valid to access one specific Entity linked to a System user within this specific Entity, and visible on the UI.