For the majority of commands, you will need to be logged in to the server. Therefore you may need to pass your authentication information along with the request.
 |
All data (including user credentials) that is sent via HTTP protocol is sent in plain text format. We recommend using HTTPS protocol for secure client/server communication. Read Configuring HTTPS to learn how to enable it. |
General Information
JSON API web service uses session authentication. Authentication data is valid only while executing batch commands that were sent in the same request. Authentication takes place inside of the JSON request. No special cookie handling is required.
To execute the commands from another request you will need to pass authentication information again.
| Tip: | To verify if you are logged in for the current batch of commands, call the Examples.checkLoggedIn command. |
The preferred way to authenticate is to send a user login and a special alpha-numeric identifier called login ticket. The benefit of login ticket is that you do not have to specify your password explicitly. Using login tickets works faster if a server uses LDAP authentication. Another benefit to login tickets is that a system admin can invalidate login tickets if they want to make sure that Collaborator clients are forced to re-authenticate.
Generating Login Tickets
To perform first-time authentication and generate a login ticket when single sign-on authentication is disabled, use the SessionService.getLoginTicket command. It accepts user login and password as input arguments and returns a login ticket which you can use in your subsequent requests.
The following request logs in as "jsmith" with password "qwerty12345" and obtains a login ticket for further usage:
[
{"command" : "Examples.checkLoggedIn"},
{"command" : "SessionService.getLoginTicket",
"args":{"login":"jsmith","password":"qwerty12345"}},
{"command" : "Examples.checkLoggedIn"}
]
The server will send the following response:
[
{ "result" : { "loggedIn" : false } },
{ "result" : { "loginTicket" : "0123456789abcdef0123456789abcdef" } },
{ "result" : { "loggedIn" : true } }
]
To perform first-time authentication and generate a login ticket when single sign-on authentication is enabled, use the Generate Login Ticket button of User Preferences page.
Authenticating With Login and Login Ticket
To authenticate using a login and login ticket use the SessionService.authenticate method. It accepts user login and login ticket as input arguments.
The following request logs in using a login ticket:
[
{"command" : "Examples.checkLoggedIn"},
{"command" : "SessionService.authenticate",
"args":{"login":"jsmith","ticket":"0123456789abcdef0123456789abcdef"}},
{"command" : "Examples.checkLoggedIn"}
]
The server response will be:
[
{ "result" : { "loggedIn" : false } },
{ "result" : {} },
{ "result" : { "loggedIn" : true } }
]