Integration
To achieve SSO with HC control panel, we are providing token based authentication. Customers who want to integrate HC10 in their own portal or any other system, can use token to auto login to control panel without providing credentials.
Token Generation
Tokens are used for authentication. A token may be issued by calling the “/auth-tokens” API endpoint for a specified number of hours, using your HC “username” and “password”. The generated token can then be used in subsequent requests to HC API.
The /auth-tokens API endpoint can be called as:
POST /auth-tokens HTTP/1.1
Host: localhost:8798
Authorization: Basic YXBpYWRtaW46QnpKWUlycXA=
Content-Type: application/json
Accept: application/json
{
"LoginName": "yourusername",
"Password": "yourpassword",
"ApplicationName": "My Thirdparty App",
"ExpiresIn": 1
}
This will return the following response:
{
"UserId": 1
"AuthToken": "57aa807c-32fc-4b71-a50e-a67a096e149b",
"ExpiresIn": 1,
"IssuedOn": "3/27/2017 5:42:04 PM",
"IsExpired": false,
"ApplicationName": "My Thirdparty App"
}
Note: Unit of ExpiresIn value is Hour
Get Token Details
Complete token details may be viewed by calling “Get Token Details” as:
GET /auth-tokens?token=57aa807c-32fc-4b71-a50e-a67a096e149b HTTP/1.1
Host: localhost:8798
Authorization: Basic YXBpYWRtaW46QnpKWUlycXA=
Content-Type: application/json
Accept: application/json
Which will return the following response and primarily includes the number of hours left for the token to expire:
{
"UserId": 1,
"AuthToken": "57aa807c-32fc-4b71-a50e-a67a096e149b",
"ExpiresIn": 1,
"IssuedOn": "3/27/2017 5:42:04 PM",
"IsExpired": false,
"ApplicationName": "My Thirdparty App"
}
Revoke Token
Similarly, the token may also be revoked anytime by calling “Revoke Token” as:
DELETE /auth-tokens?token=57aa807c-32fc-4b71-a50e-a67a096e149b HTTP/1.1
Host: localhost:8798
Authorization: Basic YXBpYWRtaW46QnpKWUlycXA=
Content-Type: application/json
Accept: application/json
Hosting Controller API
Restful API Overview
HC REST based API is a complete toolkit that includes easy to understand documentation, programming interfaces and examples so that you can integrate it in your application in a simple way. The API uses HTTP as its transmission protocol and supports JSON & XML media types for all its endpoints. It uses some specific request and response headers such as:
- Request Headers
- Accept - Specifies the server about the accepted media types of this client.
- Authorization - Specifies the server whether the user is authorized or not.
- Content-Type - Specifies the server about the syntax of the request in the message body.
- Response Headers
- Location - Specifies the server about the location of the new resource.
Generally, a REST based API is different in many ways from other APIs. One of them is the concept of resources. In case of RESTful API, everything in domain is a resource. Following are the possible resources of HC API:
In RESTful API every resource has a representation and a public URI as well. In HC REST based API there are four types of actions that can be performed on the resources such as:
- HTTP POST (used to add a resource)
- HTTP PUT (used to update a resource)
- HTTP GET (used to search a resource)
- HTTP DELETE (used to remove a resource)
HTTP Basic Authentication does not need cookies, session, identifiers and login pages. Instead of that it uses static HTTP headers for authentication purposes. Therefore, it is termed as the simplest technique to authenticate web resources.
Authentication and Authorization are two different processes that are involved in Basic Authentication such as:
- Server Side Protocol
The authentication request is sent with 'HTTP 401 Not Authorized' response code and a 'www-Authenticate HTTP' header to the client. Mostly the Authentication header looks like: www-Authenticate: Basic realm="nmrs_m7VKmomQ2YM3:"
- Client Side Protocol
The Authorization header is used to send authentication credentials to the server. Mostly, the Authorization header looks like:
Authorization: Basic aGNhZG1pbjpoY2FkbWlu==
HC API supports both the media types such as JSON and XML. Following is the resource representation of a user instance resource showing both the media types:
|
JSON
|
XML
|
|
{
"OwnerId": 0,
"UserName": "hcadmin",
"Password": "hcadmin",
"Description": "",
"IsDisabled": false,
"RoleId": 1,
}
|
<Response>
<OwnerId>0</OwnerId>
<UserName>hcadmin</UserName>
<Password>hcadmin</Password>
<Description></Description>
<IsDisabled>false</IsDisabled>
<RoleId>1</RoleId>
</Response>
|
Restful API Documentation