Session API
Bridgekeeper uses a cookie/token based authentication mechanism to manage user sessions.
Session cookie
Bridgekeeper uses an HTTP session cookie to determine if a user is logged in and to control access to various APIs accordingly. A session cookie has an expiration time and is valid until the cookie expires or the user logs out.
A session cookie qt-auth
is set in the users browser when he/she is successfully logged in via making a POST call to /api/auth/v1/login
.
API Sequence Diagram
Below API sequence diagram describes the user session management via Session cookie.
![Social Login Web Flow](/bridgekeeper/img/session-cookie.png)
Sample CURLs
Refer to Swagger API docs for more info on API usage.
Login
curl --request POST 'https://<client-domain>/api/auth/v1/login' \
--data-raw '{"username":<username>,"email":<email>,"password":<password>}' \
--compressed
Validate User Session
curl --request GET 'https://<client-domain>/api/auth/v1/sessions/validate' \
-H 'x-qt-auth: <qt-auth>'
Get User Sessions
curl --request GET 'https://<client-domain>/api/auth/v1/sessions' \
-H 'x-qt-auth: <qt-auth>'
Logout
curl --request GET 'https://<client-domain>/api/auth/v1/logout'
-H 'x-qt-auth: <qt-auth>'
Session Token
A session token is a one-time bearer token that provides proof of authentication and may be redeemed for a session in Bridgekeeper. Session tokens can only be used once to establish a Session for a user and are revoked when the token expires. Bridgekeeper creates session tokens when users successfully log in via Social Login or SSO authentication.
When a user is authenticated via Social Login or SSO authentication.
- The User needs to make a provider callback call to procure access token via a
GET
call to/api/auth/v1/:provider/callback
On successful callback Bridgekeeper returns an access token and sets the qt-auth in cookies and logs in the user. - The Session token procured in the above step can be validated via a
GET
call to/sessions/access-token/validate?redirect-url=&access-token=&redirect=
if its a valid tokenqt-auth
is set as the cookies in the browser. - In order to limit the number of logged in sessions per user, bridgekeeper provides
auth/v1/kick
endpoint, which resets all other sessions of the user except the current session. /api/auth/v1/sessions
endpoint provides the number of active sessions per user, this information is also returned in theapi/auth/v1/login
call response.
API Sequence Diagram
Below API sequence diagram describes the user session management via Session token.
![Social Login Web Flow](/bridgekeeper/img/session-token.png)
Sample CURLs
Refer to Swagger API docs for more info on API usage.
Social Login
curl --request GET 'https://<client-domain>/api/auth/v1/login?auth-provider=google&redirect-url=<redirect-url>'
Provider Callback
curl --request GET 'https://<client-domain>/api/auth/v1/google/callback?state=<state>โ
Validate Session Token
curl --request GET 'https://<client-domain>/api/auth/v1/sessions/access-token/validate?access-token=<access-token>&redirect-url=<redirect-url>'
-H 'x-qt-auth: <qt-auth>'
Kill all User Sessions
curl --request GET 'https://<client-domain>/api/auth/v1/kick'
-H 'x-qt-auth: <qt-auth>'