Kaseya Community

The new REST API in VSA R9.3

  • Hello,


    Has anyone managed to set up a connection with the new REST API?

    I cannot get this working with the provided Kaseya R93 documentation.

    Seems I cannot get passed the Authorization part.


    Regards,

    Pattie

  • I'm not on 9.3 yet, but am very keen to know that the API can do - are you able to post a link to the docs?

  • Aha, poking random numbers into my existing 6.3 url got me there!

    help.kaseya.com/.../index.asp

  • The docs are at help.kaseya.com/.../index.asp - there's a PDF and an online version, which the previous poster has linked to.

  • I may have not been very clear about this but I have read the documentation, however I still can't manage to connect to the API.

    For example, I have no idea what Authorization type to use. I assume it is OAuth2.0 because of the "bearer" but than I need an access token url, which is nowhere to be found, and the user credentials will most likely need to be hashed but I have no clue what type of hash.

    I was hoping that someone already looked into the new REST API and could provide me with the necessary information.

  • I think the documentation is woefully inadequate. (Edit - removed obviously wrong response!)

    I think Kaseya simply needs to provide a much greater level of detail - e.g. the help example given includes the text "Notice the header contains an Authorization attribute. This was returned in a previous Auth command." i.e. the help itself assumes you've already achieved a successful AUTH. Gaah.

    In my book, if you do't document the AUTH step, how the hell do you expect us to get past square one...



    corrections
    [edited by: Craig Hart at 3:51 AM (GMT -7) on May 30, 2016]
  • Thanks for looking into this Craig Hart, I am glad to hear that it's not just me.

    It does indeed look like the help assumes that you have already achieved a successful auth.

    I hope Kaseya will provide us with more information about how to set up the auth very soon because my colleagues and I are very enthusiastic about this new REST API.

  • If I'm reading it correctly, we haven't upgraded to 9.3 yet so I can't actually test, but I'm pretty sure I'm correct. Your first call needs to be to the Get Authentication (/auth) method.

    help.kaseya.com/.../9030000

    This states you need to provide a VSA Admin username and password (plain text secured by HTTPS) as HTTP headers. Without opening Visual Studio, in .NET it would be something like:

    HttpWebRequest req = new WebRequest.Create(VsaApiUrl + "/auth");

    req.Method = "GET";

    req.ContentType = "application/json";

    req.Headers.Add("username", "adminUser");

    req.Headers.Add("password", "adminPass");

    HttpWebResponse resp = req.GetResponse();

    StreamReader reader = new StreamReader(resp.GetResponseStream());

    string authJson = reader.ReadToEnd();

    The variable authJson should contain the JSON listed in the auth help page. Inside that JSON, there is a Token field.

    On every subsequent API call, you have to add the header to include the token:

    req.Headers.Add("Authorization", "Bearer " + token);

    Again, I haven't upgraded yet, so I can't test and post actual working code, but I'm pretty confident this is what the documentation is saying.



    Forgot a couple parentheses to indicate a method vs. property.
    [edited by: jondle at 8:46 AM (GMT -7) on May 31, 2016]
  • Dear Jondle,

    Thanks for your help, I asked my application developer to try this out but unfortunately it did not work.

    Still stuck on the auth part, we keep getting a "400 bad request".

    {

     "ResponseCode": 4000001,

     "Status": "Failed",

     "Error": "Missing Authorization Header"

    }

    We don't use HTTPS in the test environment, I assume this is not causing this error.

    VSA account used for AUTH has master role.

  • I'm slated to upgrade in about three weeks. Once upgraded I'll be able to poke around and confirm things. I'm pretty confident that my approach is correct, but it is obviously missing something. In the documentation, most other methods list "Authorization" under Headers, but the /auth method doesn't. So, either you aren't calling to /auth or, more likely, the error message isn't reporting correct information.

    I guess the other option is a bug with the API, but I find that unlikely since absolutely none of the API works without this step. I thought Kaseya was building their modules on the REST API, so I have to believe it works, right?

    Sorry I'm not more help. I'll look into it once we get upgraded.

  • Sounds like it's time to put in a support ticket.

  • Guys,

    With the introduction of the new REST APIs we also introduced a proper authN and authZ model to create truly scalable SOA in VSA. This includes moving towards using proper access tokens and refresh tokens through JSON Web Tokens (JWT) in the authorization headers as part of the OAuth 2.0 standard.

    Behind the scenes this is using the same stack we use in AuthAnvil to provide the security subsystem across interdependant server architectures. We purposely left out the OAuth registration and consent components in v9.3 as we need to time to finish exposing all the endpoint documentation so our customers and TAP partners can properly register their applications to securely connect to the web services and take advantage of the signed JWTs going forward. And we have to maintain the legacy of the app session ids that VSA currently uses while doing this.

    We use all this ourselves in LiveConnect to talk to our web services in the VSA.

    What does that mean for you right now? We do not have the documentation you are asking for directly available. TAP partners have early access to work with our team to get what they need; we will open it up more later this summer with full documentation and samples as time permits.

    To get you started though, here is the methodology:

    * Send a GET to the /api/v1.0/auth REST endpoint, passing in your username and a hash of your password using SHA256 with the challenge value

    * In the JSON response payload is the "Token". Right now that is the app session id, which is a placeholder for the full JWT in a future patch and provides the backwards compat with legacy subsystems.

    * Any other REST endpoint you call that has a need for a bearer token, use that token.

    From there you should have no problem accessing the REST services.

    HTH. Good luck.

  • Dana, this still isn't enough information.

    What do you mean by "passing in your username and a hash of your password using SHA256 with the challenge value" exactly:

    - Are the parameters passed as URL arguments or HTTP headers?

    - What are the actual parameter names? If we don't know the names of parameters we can't successfully pass anything to the API.

    - What is the challenge value, exactly? -is this something we supply or something we need to read from somewhere? how do we generate it (if it's a value we supply)?

    I'm sorry but you're going to need to spell it out in a lot more detail in order for us to follow how to connect. something like a step-by-step run through of how to use something like Postman [The tool Kaseya recommends to use for debugging REST API interaction] to successfully execute an AUTH would be good.

    "What does that mean for you right now? We do not have the documentation you are asking for directly available. TAP partners have early access to work with our team to get what they need; we will open it up more later this summer with full documentation and samples as time permits."

    Kaseya, you made a HUGE deal about the new REST API - it's been a major selling feature of R9.3, and is prominently advertised on the roadmap, in the release notes, and was also promoted in all the 9.3 webinars.

    Now you tell us it's actually not usable yet to us mere paying customers, and in fact Kaseya has taken deliberate steps to conceal this fact by omitting the vital ingredient from the documentation. I don't buy that the documentation isn't available, either. I'm sure it's 100% available (TAP partners are receiving it, no doubt) but since you don't want us mere paying customers to use it, you've tried to keep it secret - no doubt as some form of damage control.

    If you didn't want the REST API being used by your clients, you shouldn't have advertised it as existing and ready to use. But the cat is already out of the bag, so to speak, so either eat some humble pie and withdraw the REST API from public use as "not ready yet", or give us the proper documentation.

  • Craig,

    Thank you for reconfirming for me why it's important for us to invest in building samples and developer documentation. Not all of our customers know how to consume and interrogate REST web services.

    The REST API is available to anyone who wishes to use it. If you know how to consume REST services with your development tools you can interface with it right now. I already gave you information on where the endpoint was, and from that your tools should be able to pull the metadata definitions down and fully use them.

    We want people to use our REST APIs; however right now we believe the investment should be to help our TAP partners port their applications to take advantage of the new web services, and have all development teams around the world at Kaseya use them. By eating our own dog food and using it in all stuff we build going forward, we can deliver you better product, quicker. And give you the same access to data and services we use here at the company. This is part of our transparency mandate and our belief we should use open standards in what we build.

    All endpoints are self documented through the Swagger interface and that IS our documentation for the REST interfaces. However my priority right now is to ensure that we deliver the REST APIs and that we build the right SOA so everyone, from TAP partners to customers, have the ability to access their data. This is no different than when we released the SOAP interfaces years ago.

    If you know how to use REST and Swagger, you have all information right there on your server RIGHT NOW. We haven't hidden anything. We haven't misrepresented what we delivered in v9.3. The documentation I said we don't have for you is in the dev samples; its seems you could use those right now if you don't know how to consume the services.

    Now, a personal observation from me to you. I was open and honest with you that we would deliver more detailed developer documentation and samples in a couple of months, and gave you a heads up where you could start in the meantime. And your response is to negatively attack the process and Kaseya? I don't think that is a reasonable position to take.

    I want to be your advocate to make your experience in using our technologies more successful. However, you are making it extremely difficult in your tone and attitude for me to want to continue to support you in the community so openly like this. If you want to continue to work with me in making you more successful, I am open to it. But if you continue to make every post so accusational and hostile, I'm simply not going to engage with you. My time could be better served helping those customers who want to work with me and my team, instead of against it.

    Let me offer an olive branch since its apparent without the samples you are kind of stuck. From the VSA server, open up a browser and go to /api/v1.0/swagger. That will give you the pretty human readable version of the information if your tools can't grab the metadata and use it directly.

    If you need any further assistance, it will be made available to you in samples that we will provide in the next few months. If you have pressing business needs to get more support now you are welcome to contact your account manager and engage in a professional services contract like our TAP partners are doing to get assistance.  

  • I can confirm that authorization works using plain user credentials in "http://<yourVSA>/api/v1.0/swagger".

    However, it is still unclear how the Authorization header is being build. The Basic Authorization header that Swagger generates is 3 times bigger than hashing the user password with SHA256 and encoding it with the username using e.g. Base64.

    The basic (decoded) Auth header consist of:

    user=[username in plain-text],

    pass2=[hash],

    pass1=[hash],

    rand2=[probably hash, could be a number],

    rpass2=[hash],

    rpass1=[hash],

    twofapass=:undefined

    Update:
    This URL describes how the Authorization header is set up:
    "http://<yourVSA>/api/v1.0/swagger/ui/ext/Kaseya-API-Core-Swagger-SwaggerUITweaks-js"



    "http:///api/v1.0/swagger/ui/ext/Kaseya-API-Core-Swagger-SwaggerUITweaks-js"
    [edited by: Pattie at 2:00 AM (GMT -7) on Jun 2, 2016]