Sessions

Initiating a Single-Sign-on Session for a Contact Person

curl http://hostname/webservice/sessions \
  -u webservice:apikey \
  -X POST \
  --form-string session[{login,password}]=login,password

The resulting document contains the internal session ID, the contact person’s ID, the session expiry date, and a unique session identifier (token). The token associates the session with the contact person’s ID.

<?xml version="1.0" encoding="UTF-8"?>
<session>
  <contact_id type="integer">1</contact_id>
  <token>886cdbbf48032d1588567936580c518a</token>
  <valid_until type="datetime">2009-08-12T17:53:55+02:00</valid_until>
</session>

Checking and Renewing a Single-Sign-on Session

To prevent a single-sign-on session from expiring, it needs to be renewed.

curl curl http://hostname/webservice/sessions/session \
  -u webservice:apikey \
  -X PUT \
  --form-string "session[token]=token_string"

If the session exists, the original session data is returned, except for the updated expiration date. If the session no longer exists, the status code 422 as well as detailed information in the body of the response are returned. Example (for proper display, the cookie was divided into 2 lines):

HTTP/1.1 422
Connection: close
Date: Mon, 24 Aug 2009 16:16:10 GMT
X-Runtime: 33
Content-Type: application/xml; charset=utf-8
Cache-Control: no-cache
Set-Cookie: _omc_session=BAh7BjoPc2Vzc2lvbl9pZCIlNzcyMDAzOTg1NDk0MzZiYjk4MDk5
ZDZlZGZjOTJlYjU%3D--482e16f595f7c8b6efc57bae38e2b629925be318; path=/; HttpOnly
Content-Length: 98

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Authentication failed.</error>
</errors>

Invalidating a Single-Sign-on Session

curl curl http://hostname/webservice/sessions/session \
  -u webservice:apikey \
  -X DELETE \
  --form-string "session[token]=token_string"

If the session specified does not exist, the status code 422 and the error message shown above is returned, plus the following pieces of information in the header:

TOKEN_STRING=token_string
header show
execute 9

If the session existed, the body of the response contains a corresponding message:

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <message>Session deleted.</message>
</hash>