Applies to Collaborator 12.1, last modified on August 21, 2019

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. Besides, the users will have an option of invalidating login tickets if they want to make very sure they are logged out of the system everywhere.

Generating Login Tickets

To perform first-time authentication and generate a login ticket, 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" 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 } }

]

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 } }

]

See Also

JSON API Web Services
Configure HTTPS

Highlight search results