WIXLIB

2018Vertex REST API SpecificationCLOUD INTEGRATION GUIDE

2301 Renaissance Blvd King of Prussia, PA 19406800.355.3500 610.640.4200Copyright and legal noticesCopyright 2018 Vertex Global Tax Solutions Ireland Holdings. All rights reserved. This documentation may not bereproduced, displayed, distributed, modified, posted, republished, or transmitted in any form or by any means,without the prior written consent of Vertex Global Tax Solutions Ireland Holdings or its affiliates (collectively,“Vertex”), except as otherwise specified in a valid, current Vertex license agreement or allowed by law.DisclaimersThe information contained in this documentation is designed to help users in regard to the subject matter covered.Some of it may be based upon interpretations of federal, state, foreign and other tax laws and regulations. Eachentity is responsible for making its own determination of how such laws and regulations apply to its owncircumstances and for evaluating the capabilities of, and all data and results generated by, any product that isdescribed in this documentation. Vertex is not engaged in providing legal, tax or accounting advice or services andthe information contained in this documentation or in any product cannot replace the advice of competent legalcounsel. Further, the information in this documentation is subject to change without notice and is not warranted tobe error-free. If you find any errors, please report them to us in writing.Trademarks and Service MarksThe trademarks, logos and service marks ("marks") displayed in this documentation are the property of Vertex GlobalTax Solutions Ireland Holdings and its affiliates or other third parties. Users are not permitted to use these markswithout the prior written consent of Vertex Global Tax Solutions Ireland Holdings, its affiliates or the third party thatmay own the mark.Third Party ProductsCopies of the licenses for some third-party products included with a Vertex product may be found in or with theinstallation materials for that productvertexinc.com

2301 Renaissance Blvd King of Prussia, PA 19406800.355.3500 610.640.4200ContentsIntroduction . 4Invoking the Security Token Service (STS) to obtain an access token . 4Obtaining the token endpoint . 4Obtaining the access token . 4Using an access token to authorize a request . 5

2301 Renaissance Blvd King of Prussia, PA 19406800.355.3500 610.640.4200IntroductionThe Vertex REST API requires a valid access token to be supplied to invoke any of its methods. Thisdocument describes the steps necessary to request an access token for the REST API with Vertex Cloud.Invoking the Security Token Service (STS) to obtain an access tokenTo retrieve an access token for using the Vertex REST API with Vertex Cloud, a call must be made to theVertex Cloud STS. The STS implements the OpenID Connect specification and exposes the well-knownOpenID configuration page.Obtaining the token endpointUse the well-known configuration endpoint (/identity/.well-known/openid-configuration) on the STSendpoint’s root URI to retrieve the value of the token endpoint. The token endpoint value is the URL toinvoke to obtain an access token for the Vertex REST API.Below is a sample response fragment from the well-known configuration endpoint:{"issuer" : " https://localhost","jwks uri" : horization endpoint" : ken endpoint" : fo endpoint" : "https://localhost/identity/connect/userinfo","end session endpoint" : heck session iframe" : "revocation endpoint" : "https://localhost/identity/connect/revocation", }NOTE: All URLs in this sample are for illustration purposes only. The localhost value will bereplaced with the root URI of the STS.It is preferred that the consuming application make the call to the well-known configuration endpointregularly. Regularly checking the token endpoint value allows the consuming application to adapt to anypossible token endpoint URI changes in the future.Obtaining the access tokenSubmit a request to the URL in the token endpoint using an HTTP POST. To get an access token, thefollowing parameters must be provided in the request body:Parameter Nameclient idclient secretDefinitionThe Vertex Cloud supplied client identifier for thecustom integrationThe Vertex Cloud supplied client secret for thecustom integrationTypeString, RequiredString, Required

2301 Renaissance Blvd King of Prussia, PA 19406800.355.3500 610.640.4200Parameter Nameusernamepasswordscopegrant typeDefinitionThe API key from Vertex Cloud for the client onwhose behalf the calls will be madeThe API password from Vertex Cloud for the clienton whose behalf the calls will be madeMust contain the string ‘calc-rest-api’ (without thequotes)Must contain the string ‘password’ (without thequotes)TypeString, RequiredString, RequiredString, RequiredString, RequiredThe client id and client secret parameters are issued for each integration against the REST API. They areconfidential values and should not be exposed to any users of the integration. The username andpassword are the values that identify the Vertex Cloud account on behalf of which to operate. Thesemust be provided to the integration and can vary if there are multiple installations of the integration orif the integration is used for more than one Vertex Cloud account.The response from the call to the token endpoint is a JSON object.In the case of an error (HTTP Status code ! 200), the JSON object has one property “error” with amessage as to the reason for failure. For example:{"error" : "invalid client"}In the case of success (HTTP Status Code 200), the JSON object has multiple properties. For example:{"access token": "f81003774475c019d775277f0b29e527","token type": "Bearer","expires in": 1200}In the success case, the access token and token type are needed to make calls against the Vertex RESTAPI. The expires in value defines the number of seconds until the access token expires. After this time,a new token must be requested.Using an access token to authorize a requestWhen making requests against the REST API endpoints, the access token must be set in the ‘Authorization’header of the request with the token type and access token. For example:Authorization: Bearer {ACCESS TOKEN}Or, using the above response as an example:Authorization: Bearer f81003774475c019d775277f0b29e527

2301 Renaissance Blvd King of Prussia, PA 19406 800.355.3500 610.640.4200 Introduction The Vertex REST API requires a valid