Single Sign On

Version 4 of VINx2 supports a Single Sign On feature that allows a user to sign in to VINx2 from an approved API Partner application without needing to resupply their log-in credentials.  For instance, a mutual customer might want to jump from your CRM/Wine Club software straight into VINx2 so they can look at how much stock they have available before confirming a large order.

To request your application’s approval, please contact us at vinx2.com.

This is a RESTful web service at a URI relative to the customer’s VINx2 application.  The URI for the service follows this convention:

https://<BASE_SERVER_ADDRESS>/<DBNAME>/api/v4/auth/sso

For instance, if the customer’s VINx2 application was typically accessed at:

https://demo.vinx2.net/mywinery/app

The Single Sign On end point would be accessed at:

https://demo.vinx2.net/mywinery/api/v4/auth/sso

The service uses Basic HTTP Authentication.  The username and password will be assigned to you and will be specific to a particular customer application instance.

This service supports both JSON and XML content types for PUT and POST.

The request supports the following three fields:

  • partnerKey (required): this is the API Partner Key that has been assigned to you by VINx2 staff, and is specific to each customer’s application that you are connecting to.
  • accountName (required): this is the user account username that you are requesting access for.
  • context (optional): this field is optional and will allow you to provide a context string to ask the VINx2 application to take you to a certain area of the application (for instance, you may want to launch winery set up directly, or jump straight to a certain report).  Note that a list of available options will be provided in the future, as this feature is still under construction.

The following example shows a Single Sign On Request in XML (be sure to set your “Content-type” header to “application/xml”):

<SingleSignOnRequest>
    <partnerKey>JKWajkajaUHSAjk2673J</partnerKey>
    <accountName>jsmith</accountName>
    <context></context>
</SingleSignOnRequest>

The following example is for the same details, but in JSON format (be sure to set your “Content-type” header to “application/json”):

{
    "partnerKey": "JKWajkajaUHSAjk2673J",
    "accountName": "jsmith",
    "context": ""
}

You will then get a response signifying success or failure, along with a one-time URL that will grant you access to the VINx2 application as the requested user.  The response will contain the following fields:

  • success: true or false if the request was successful or not.
  • message: an status message to give a reason if there was an error.  Possible values are:
    • Invalid API request: the request was not valid
    • Invalid API key: the API partner key did not match or verify
    • Invalid API username: the username you were accessing the API with did not match the one that is linked to your API Partner record
    • Invalid user account: the user account you are trying to access is incorrect or disabled
    • The user account does not have auto login enabled: the account does not have the auto logic option enabled which is required for it to be able to grant access for the single sign on API
    • Service temporarily unavailable: a server error caused a failure
    • Success: the request was successful
  • authToken: the one-time authentication token
  • redirectURL: a complete URL that contains the one-time authentication token that can be used to view the user’s VINx2 application (e.g. in another window or in an iframe)

By using the “Accept” HTTP header in your request, you can determine which format you receive the response in.

For XML, set your “Accept” header to “application/xml” and you will receive something along the lines of:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SingleSignOnResponse>
    <authToken>hJGH87261267hjKH</authToken>
    <message>Success</message>
    <redirectURL>https://demo.vinx2.net/mywinery/app?apiAuthToken=hJGH87261267hjKH</redirectURL>
    <success>true</success>
</SingleSignOnResponse>

And the same example as JSON with “Accept” header set to “application/json”:

{
  "success": true,
  "message": "Success",
  "authToken": "hJGH87261267hjKH",
  "redirectURL": "https://demo.vinx2.net/mywinery/app?apiAuthToken=hJGH87261267hjKH"
}

The following is an example of a JSON response where there has been a failure caused by the API partner account not matching the account the request came in on:

{
  "success": false,
  "message": "Invalid API username",
  "authToken": null,
  "redirectURL": null
}

If you would like more information about becoming a VINx2 API partner, please contact us here.

Leave a Reply

Your email address will not be published. Required fields are marked *