Login
The Login API allows you to login to the application by providing your user name and password. If the login is successful, the application returns a unique session identifier. For security purposes, you are required to pass this identifier with each subsequent request.
|
Action |
Method |
URL |
Description |
|
POST |
api/authenticate/user |
Authenticates a user and creates a new session. |
|
|
POST |
api/user/logout |
Ends the specified session. |
Log In
Logging in validates your user credentials and creates a new user session. After successfully logging in, you will receive a unique encrypted session identifier that must be included in the header of all other API requests. This session id is the authentication token that allows you to send requests without having to send your credentials every time.
IMPORTANT: Your session ID uniquely identifies your active session. If your session ID is shared or stolen, other users will be able to log in as your user. We highly recommend using SSL to secure your communications with the REST API.
Request Information
A Login request sends the username and password of the user you wish to log in as to the application server for authentication.
URL
api/authenticate/user
Method
POST
Body Parameters
The Log In endpoint requires the username and password of a user.
Tip: To log in as a domain user, add an extra backslash between your user name and the domain name.
|
Parameter |
Description |
Type |
Example |
|
username |
Your user name. |
String |
mydomain\\myuser |
|
password |
Your password. |
String |
password |
Sample Request Snippet
URL: https://application-server/cgrestapi/api/authenticate/user
Body: {
"username": "domain\\username",
"password": "password"
}
Response Information
If the login is successful, the response contains the generated session ID, the user's unique ID, and a collection of the user's privileges.
Body Parameters
Successful authentication returns an encrypted session ID token along with the user's privileges.
|
Key |
Description |
Type |
Example |
Additional Information |
|
sessionId |
An encrypted session ID used with other REST API requests. |
String |
ap9pYaaBK8K5iMNZNC5DtA== |
The REST API requires this value in the header of all other requests. |
|
userId |
The unique ID of the authenticated user. |
String |
159 |
|
|
UserPrivileges |
List of privileges for the user. |
JSON array. |
"UserPrivileges": { "Workspace": {...}, "Incident": {...}, "ServiceCatalog": {...}, "Teams": {...}, ... } |
UserPrivileges are separated by module. Each module defines the actions that the user can and can not perform within the module. Each module lists the following attributes:
|
Sample Response
{
"sessionId": "EhbNKWgPZNJnHRPJ3PfvLrtavbL591sfEVzR3Hn/Fs7RCBceNxpWIuhw0iIn8YM",
"userId": "10",
"UserPrivileges": {
"Workspace": {
"fieldBasedSecurity": "false",
"actionsDenied": "AdministerModule,Edit,View",
"actionsAllowed": "ViewOwn,Edit Own,DrillDown",
"factoryAllowedActions": "ViewOwn,Edit Own,DrillDown,VisibletoUser",
"actionsAllowed_Value": 196608,
"possibleActions": "AdministerModule,View,ViewOwn,Edit,Edit Own,DrillDown",
"VisibletoUser": "true",
"entityType": "",
"name": "Workspace"
},
"ServiceCatalog": {
"fieldBasedSecurity": "false",
"actionsDenied": "Add,AdministerModule,Edit,Edit Own,ManageCategories,View,ViewOwn,ViewTeam,Email,Print,Copy,Retire,Send,Republish,Publish,Revise,Delete,Request Review",
"actionsAllowed": "",
"factoryAllowedActions": "None,VisibletoUser",
"actionsAllowed_Value": 0,
"possibleActions": "Add,AdministerModule,Edit,Edit Own,ManageCategories,View,ViewOwn,ViewTeam,Email,Print,Copy,Retire,Send,Republish,Publish,Revise,Delete,Request Review",
"VisibletoUser": "true",
"entityType": "SDInterfaces.Entities.IServiceItem",
"name": "ServiceCatalog"
},
...
}
}
Log Out
Logging out ends the session for the specified session ID.
Request Information
Logging out simply requires you to provide the ID of the session you wish to end.
URL
api/user/logout
Method
POST
Header Parameters
The logout API requires the ID of the session to close.
|
Parameter |
Description |
Type |
Example |
|
sessionid |
The encrypted session ID. |
string |
EhbNKWgPZNJnHRPWJ3PfvLrtavbL591sfEV |
Request Sample
URL: https://application-server/cgrestapi/api/user/logout
Header: sessionid: EhbNKWgPZNJnHRPWJ3PfvLrtavbL591sfEV
Response Information
The REST API returns an empty response whether the logout was successful or unsuccessful. If the logout was successful, the session will no longer work for future requests.