Session Management
This page is about the legacy SOAP-based jxAPI that is no longer updated or recommended for use in new projects. The documentation in this section may be outdated or inaccurate, and is provided for reference purposes only.
Journyx recommends using the REST-based API for new projects in most cases. However, at the current time, there are certain object types that are not available through the REST API.
Most operations on time and expense data require authentication. The Journyx server uses a session-oriented authentication system, based on named users with passwords. To use most of this interface, the client must identify itself to the server and establish access rights based on an existing user.
To establish an authenticated session, the client must call the
login method, passing a valid user name and
password. If the login is successful, the return value will be a string
containing a session key. The session key is a unique, opaque value; your
program must pass a valid session key as the first argument to every method that
requires authentication. (In the rest of this document, this argument will be
shown in function prototypes as "skey", and not described in detail each time.)
The client may establish more than one session if necessary; each will get a
unique key.
Another thing to keep in mind is that the login
method may generate a fault if the username or password is incorrect, or in some
other situations as documented below for login.
You should check for these faults and handle them appropriately.
In the web-based user interface, each session has a timeout after which its authentication cookie becomes invalid, forcing the user back to the login screen. Sessions established using the jxAPI also have a time limit; attempts to use a session key after the session timeout has elapsed will result in a fault. Once that occurs, the client will then be required to create a new session in order to continue using the server.
In practice, the timeout will be long enough that it should not occur during a typical interactive session. The session timeout is configurable (through the web interface) in the Global Preferences section "Security and Access" under the preference named "Idle time before a user is forced to relogin (minutes)."
When you are finished with the session, it is recommended to call the
logout() method to invalidate the session key.