Sign On Dealership Web Service Specification

Overview

Account Sign-On Dealership 

This service will allow users to pass directly into Aimbase without having to authenticate and can also create new dealer accounts.  The appropriate security settings will be part of the API call and will determine what the account is allowed access to within the Aimbase instance. 

Endpoint URL  

https://{baseaddress}/api/Security/SingleSignOn   

Request 

The request is an HTTP Post to the endpoint. The Content-Type header may be application/json (if sending the request in a JSON format) or application/xml (if sending the request in an XML format).  The request body must contain all required fields.  The ApiToken header with a valid API token must be included in the message header. 

Field 

Max Length 

Req’d 

Description 

Username 

 

Yes 

The username of the user that is logging in. 

Hierarchies 
 

Yes 

A collection of security hierarchies to assign to the user account.  These will be passed as a collection of hierarchy type and code pair values.  Hierarchies must be submitted with at least one Manufacturer and at least one Dealer. If more than one Manufacturer or Dealer is given, the account will be restricted to all combinations of the Dealers in the Manufacturers. 

 

An example of restricting a user account to a dealer across multiple manufacturers would be: 

 

Hierarchies: 

[ 

    {“Type”: “Manufacturer”, “Code”: “M1” }, 

    {“Type”: “Manufacturer”, “Code”: “M2” }, 

    {“Type”: “Dealer”, “Code”: “1000-1” } 

] 

 

An example of restricting a user account to multiple dealers in one manufacturer would be: 

 

Hierarchies: 

[ 

    {“Type”: “Manufacturer”, “Code”: “M1” }, 

    {“Type”: “Dealer”, “Code”: “1000-0” }, 

    {“Type”: “Dealer”, “Code”: “1000-1” } 

] 

FirstName 

 

No 

The first name of the user account 

LastName 

 

No 

The last name of the user account 

Email

 

No 

The email address of the user account.   

 

NOTE: this is used to match with other notifications that are sent out by Aimbase and using a shared email address for multiple accounts can cause undesired results.  Recommended to use a unique email address for each user. 

LandingPageUrl 

 

No 

The url path that the user account should be sent to after the authentication process is complete and the user has been redirected to Aimbase.  This should be the relative path from the base url. 

AccountTypeName 

 

No 

The type of account that should be created. Valid values are: Single Sign On and Single Sign On Admin 


Example JSON  

{ 
    "Username" : "johnd", 
    "Hierarchies" :  
    [ 
        {"Type":"Manufacturer","Code":"M1"}, 
        {"Type":"Dealer","Code":"10196"} 
    ], 
    "FirstName" : "John", 
    "LastName" : "Doe", 
    "Email" : "John@Doe.com", 
    "LandingPageUrl":"/CSI/Registration", 
    "AccountTypeName":"Single Sign On" 
} 

 Example XML 

<SsoRequest> 
    <Username>johnd</Username> 
    <Hierarchies> 
        <Hierarchy> 
            <Type>Manufacturer</Type> 
            <Code>M1</Code> 
        </Hierarchy> 
        <Hierarchy> 
            <Type>Dealer</Type> 
            <Code>10196</Code> 
        </Hierarchy> 
    </Hierarchies> 
    <FirstName>John</FirstName> 
    <LastName>Doe</LastName> 
    <Email>John@Doe.com</Email> 
    <LandingPageUrl>/CSI/Registration</LandingPageUrl> 
    <AccountTypeName>Single Sign On</AccountTypeName> 
</SsoRequest> 


Response 

If the request is valid the return message will have an HTTP Status Code of 200 (OK) and contain the location that the user should be redirected to. 

 

If the request format is incorrect, the return message will have an HTTP Status Code of 400 (Bad Request) and the response body will contain an error message. 

Example JSON 

{"Message":"The Username field is required."} 

Example XML 

<Error><Message>The Username field is required.</Message></Error> 

 

If the request content is incorrect or another error occurs in the service, the return message will have an HTTP Status Code of 500 (Internal Server Error) and the response body will contain an error message. 

Example JSON 

{"Message":"Hierarchy code ‘Brands’ was incorrect."} 

Example XML 

<Error><Message> Hierarchy code ‘Brands’ was incorrect.</Message></Error>