Sessions
From Videntity Wiki - The API Documentation
Sessions are used to make a secure connection to the Videntity servers. For each session a login is required. Once logged in your session will expire in 30 minutes. To keep your session alive before the 30 minute time frame is up you must ping our server to reestablish the session and reset the session timer. To ensure security and stop session hijacking every session key is generated randomly. When finished with your session key you can logout of the session. This keeps unexpired sessions from being used.
Contents |
Before you Begin
Before you can start a session with the Videntity server you must first create a user account. During user account creation we will generate your username, user id, and password.
username: Your username is created by you when you signup for an account
foobar
user id: Your user id is a random 15 digit number
514778845023264
user password: Your password is a random 15 character string
Ry5NvPky2jBjshT
Your username, password, and user id will be used to start a session with the Videntity Server.
Starting a Session: Login
Starting a session with the Videntity server is as easy as logging on a website. All you have to do is send a form POST to the Videntity Session Login method
https://api.videntity.com/sessions/login
with your username, user, id, and password as the form POST fields URL encoded:
username=foobar&password=Ry5NvPAbceAS123&account_number=210983749212839
Your user information will then be checked with our database and the Videntity server will respond with either an error message
<?xml version="1.0" encoding="utf-8"?>
<response api_method="/user/login">
<status>ERROR</status>
<api_tx_number>12</api_tx_number>
<error_number>1</error_number>
<error_name>AUTHENTICATION_ERROR</error_name>
<error_detail>username, password or account_number is incorrect</error_detail>
<timestamp>2008-09-30 15:56:42</timestamp>
</response>
or a response with the session key:
<?xml version="1.0" encoding="utf-8"?>
<response api_method="/session/login">
<status>SUCCESS</status>
<api_tx_number>182737893</api_tx_number>
<response_name_value>
<session_key>Ry5NvPAbceAS123</session_key>
</response_name_value>
<timestamp>2008-09-30 15:56:42</timestamp>
</response>
Your session key will be used throughout your interaction with the Videntity server. Almost all API URL functions require a session key. Once your key is generated through the login URL it will start a timer.
You have exactly 30 minutes from the time you login to the time your session expires.
Once your session expires you will no longer be able to communicate with the Videntity Server. If your session key expires you must login and create another session. If you know that your application is going to be running on a current session for more then 30 minutes you can ping the session to keep it active. For more on keeping your session active see the next section.
Keeping a Session Alive: Pinging
Ever time you establish a session with the Videntity Server it starts a 30 minute session timer. The session timer is used to prevent session hijacking. We could just require you to send your username, password, and user_id with every POST. However, this could lead to someone trying to packet sniff your authentication data, even though your authentication data is going over encrypted HTTPS. So instead we use sessions to keep your authentication data safe. The only problem is that now your session boils down to single password the session key. The good news is that your session gets deleted every 30 minutes. This makes it very difficult for someone to steal your session key. However this can pose a problem for a program that runs longer then 30 minutes. So, in order to keep your session going we have provided a Session Ping method
https://api.videntity.com/session/ping
with your session_key as the form POST field URL encoded:
session_key=Ry5NvPAbceAS123
Calling the session_key method will cause the Videntity server to check the current session_key and make sure it hasn't expired. If the session key has expired you will have to generate a new session key. If the session key hasn't expired the key will be reset and you will have another 30 minutes (from the time of the ping_session call)for your session.
Closing a Session: Logout
It is always a good idea to logout of your current session when your program is done communicating with the Videntity server. To logout of your current session all you have to do is call the Session Logout method
https://api.videntity.com/session/logout
with your session_key as the form POST field URL encoded:
session_key=Ry5NvPAbceAS123
Once this method call is completed your session will be deleted. You will no longer be able to use this session key. The upside is that no one else will be able to use it either. It is strongly recommended that you logout of any session that has yet to expire when your code has finished running (this prevents session hijacking). Although, you do not have to logout of expired sessions it is still good housekeeping. However, if you do not logout we periodically delete all unused session keys.
