Sessions

Session management facilitates secure interactions between a user and an application and applies to requests and responses associated with that particular user. When users have an ongoing session with an application, they submit requests within their session and often provide potentially sensitive information. The application may retain this information and/or track the user's status during the session across multiple requests.

Session tokens serve to identify a user’s session for the RESTful API requests and are exchanged between the application and its users. RESTful API, which relies on HTTP traffic on its own, is stateless, meaning each request is processed independently, even if they are related to the same session. Thus, session management is crucial for directing these interactions and these tokens are vital as they are passed back and forth between the user and the application. Each request and response will have an associated session token that allows the application to remember distinct information about the client using it.

Through the Altogic client library, you can manage sessions of your application users. Below is the list of session management capabilities of Altogic that you can use in your service designs.

note

You can enforce sessions for your app uses through your client library key. If sessions are enforced then users need to be signed in to your app and the session token needs to be provides in Session Header of each method call made to your backend app through the client library.

You can enable/disabled session enforcement or your client library keys from App settings → Client library keys view of Designer.

Sign out a session

You can sign out a session by calling the signOut method.

note

If an input session token is not provided, this method signs out the user from the current session, clears user and session data in local storage and removes the Session header in Fetcher. Otherwise, signs out the user from the session identified by the input token.

Javascript
Dart

//Sign out a session
const { errors } = await altogic.auth.signOut(sessionToken);

//Sign out a session
final errors = await altogic.auth.signOut(sessionToken);

Parameters

Here you can find parameters for the signOut method.

#	Name	Data type	Required	Description
1	sessionToken	string	No	A session token of the user

note

An active user session is required (e.g., user needs to be logged in) to call this method.

Sign out from all sessions

You can sign out all session by calling the signOutAll method.

note

A user can have multiple active sessions (e.g., logged in form multiple different devices, browsers). This method signs out users from all their active sessions. For the client that triggers this method, also clears user and session data in local storage, and removes the Session header in Fetcher.

Javascript
Dart

//Sign out all sessions
const { errors } = await altogic.auth.signOutAll();

//Sign out all sessions
final errors = await altogic.auth.signOutAll();

note

An active user session is required (e.g., user needs to be logged in) to call this method.

Sign out all except current

You can sign out all session except the current by calling the signOutAllExceptCurrent method. It signs out users from all their active sessions except the current one which makes the API call.

Javascript
Dart

//Sign out all sessions except current
const { errors } = await altogic.auth.signOutAllExceptCurrent();

//Sign out all sessions except current
final errors = await altogic.auth.signOutAllExceptCurrent();

note

An active user session is required (e.g., user needs to be logged in) to call this method.

Get current session

You can get the current session by calling the getSession method. This method is used to get the current session of the user and returns the currently active session data from local storage.

Javascript
Dart

//Get current session
const session = altogic.auth.getSession();

//Get current session
final session = await altogic.auth.getSession();

Example response

{
  "userId": "6233247fb46a9b5bb144e797",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IhJmslSKnS2H7kpX...",
  "creationDtm": "2022-03-17T13:17:50.903Z",
  "userAgent": {
    "family": "Chrome",
    "major": "99",
    "minor": "0",
    "patch": "4844",
    "device": { "family": "Other", "major": "0", "minor": "0", "patch": "0" },
    "os": { "family": "Mac OS X", "major": "10", "minor": "15", "patch": "7" }
  },
  "accessGroupKeys": []
}

Get user info from local storage

You can get the user info by calling the getUser method. This method is used to get the user info of the user and returns the user data from local storage.

Javascript
Dart

//Get current session
const user = altogic.auth.getUser();

//Get current session
final user = await altogic.auth.getUser();
// TODO:

Example response

{
  "_id": "6233247fb46a9b5bb144e797",
  "provider": "altogic",
  "providerUserId": "6233247fb46a9b5bb144e797",
  "email": "[email protected]",
  "signUpAt": "2022-03-17T12:07:27.514Z",
  "lastLoginAt": "2022-03-17T13:17:50.878Z",
  "emailVerified": true,
  "name": "John"
}

Get user info from database

You can get the user info of the user associated with the active session from the database by calling the getUserFromDB method.

Javascript
Dart

//Get current session
const result = await altogic.auth.getUserFromDB();

//Get current session
final result = await altogic.auth.getUserFromDB();

Example response

{
  "user": {
    "_id": "6233247fb46a9b5bb144e797",
    "provider": "altogic",
    "providerUserId": "6233247fb46a9b5bb144e797",
    "email": "[email protected]",
    "signUpAt": "2022-03-17T12:07:27.514Z",
    "lastLoginAt": "2022-03-17T13:17:50.878Z",
    "emailVerified": true,
    "name": "John"
  },
  "errors": null
}

note

An active user session is required (e.g., user needs to be logged in) to call this method.

Get all active sessions

You can get all active sessions by calling the getAllSessions method.

Javascript
Dart

//Get all sessions of the user (active or not)
const result = await altogic.auth.getAllSessions();

//Get all sessions of the user (active or not)
final result = await altogic.auth.getAllSessions();

Example response

{
  "sessions": [
    {
      "userId": "6233247fb46a9b5bb144e797",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "creationDtm": "2022-03-17T13:17:50.903Z",
      "userAgent": {
        "family": "Chrome",
        "major": "99",
        "minor": "0",
        "patch": "4844",
        "device": {
          "family": "Other",
          "major": "0",
          "minor": "0",
          "patch": "0"
        },
        "os": {
          "family": "Mac OS X",
          "major": "10",
          "minor": "15",
          "patch": "7"
        }
      },
      "accessGroupKeys": []
    },
    {
      "userId": "6233247fb46a9b5bb144e797",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX...",
      "creationDtm": "2022-03-17T13:23:52.882Z",
      "userAgent": {
        "family": "Chrome",
        "major": "99",
        "minor": "0",
        "patch": "4844",
        "device": {
          "family": "Other",
          "major": "0",
          "minor": "0",
          "patch": "0"
        },
        "os": {
          "family": "Mac OS X",
          "major": "10",
          "minor": "15",
          "patch": "7"
        }
      },
      "accessGroupKeys": []
    }
  ],
  "errors": null
}

note

An active user session is required (e.g., user needs to be logged in) to call this method.

Invalidate session

You can invalidate a session by calling the invalidateSession method. It invalidates the current user session, removes local session data, and clears Session token request header in Fetcher. It is useful when the user logs out from the client.

Javascript
Dart

//Invalidates user session and clears local session data
altogic.auth.invalidateSession();

//Invalidates user session and clears local session data
altogic.auth.invalidateSession();

note

If signInRedirect is specified in ClientOptions when creating the Altogic api client and if the client is running in a browser, this method redirects the user to the sign in page.

Clear local session data

By default Altogic saves the session and user data in local storage whenever a new session is created (e.g., through sign up or sign in methods). This method clears the locally saved session and user data. In contrast to invalidateSession, this method does not clear Session token request header in Fetcher and does not redirect to a sign in page.

Javascript
Dart

//Deletes locally saved session and user data
altogic.auth.clearLocalData();

//Deletes locally saved session and user data
awwit altogic.auth.clearLocalData();

Set client session and user

Set Client Session

You can set the client session by calling the setSession method.

It sets (overrides) the active user session. If you use the signUp or signIn methods of this client library, you do not need to call this method to set the user session, since the client library automatically manages user session data.

However if you have more complex sign up or sign in logic, such as 2 factor authentication flow where you authenticate users using a short code, you might need to create your endpoints and associated services to handle these special cases. In those situations, this method becomes handy to update the session data of logged-in users so that the Fetcher can update its default headers to pass the correct session token in its RESTful API calls.

Javascript
Dart

//Sets the active user session
altogic.auth.setSession(session);

//Sets the active user session
await altogic.auth.setSession(session);

Parameters

Here you can find parameters for the setSession method.

#	Name	Data type	Required	Description
1	session	Session	No	A session of the user is an object that contains the following properties: userId, token, creationDtm, userAgent, accessGroupKey.

tip

When you use custom authentication logic in your apps, you need to call this client library method to update session data so that your calls to your app endpoints that require a valid session token do not fail.

Set User

It saves the user data to local storage. If you use the signUp or signIn methods of this client library, you do not need to call this method to set the user data, since the client library automatically manages user data.

However, if you have not used the signUp or signIn methods of this client library, this method enables you to update locally stored user data.

Javascript
Dart

//Saves the user data to local storage
altogic.auth.setUser(user);

//Saves the user data to local storage
await altogic.auth.setUser(user);

Parameters

Here you can find parameters for the setUser method.

#	Name	Data type	Required	Description
1	user	User	No	A user object that can be used to set the user info of the user in the client session.

Get authentication grants

This method returns the authorization grants of a user using the specified input accessToken. If no accessToken specified as input, tries to retrieve the accessToken from the browser url query string parameter named 'access_token'.

You can use the access_token token to get authentication grants, namely the user data and a new session object by calling the getAuthGrant method.

Javascript
Dart

//...You can get user and session data using the accessToken
const result = await altogic.auth.getAuthGrant(accessToken);

//...You can get user and session data using the accessToken
final result = await altogic.auth.getAuthGrant(accessToken);

Example response

{
  "user": {
    "_id": "6235e0eb25de47092f4d5300",
    "provider": "altogic",
    "providerUserId": "6235e0eb25de47092f4d5300",
    "email": "[email protected]",
    "signUpAt": "2022-03-19T13:55:55.772Z",
    "lastLoginAt": "2022-03-19T13:58:42.376Z",
    "emailVerified": true,
    "name": "Rooby"
  },
  "session": {
    "userId": "6235e0eb25de47092f4d5300",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbnZJZCI6I...",
    "userAgent": {
      "family": "Chrome",
      "major": "99",
      "minor": "0",
      "patch": "4844",
      "device": {
        "family": "Other",
        "major": "0",
        "minor": "0",
        "patch": "0"
      },
      "os": {
        "family": "Mac OS X",
        "major": "10",
        "minor": "15",
        "patch": "7"
      }
    },
    "accessGroupKeys": []
  },
  "errors": null
}

Parameters

Here you can find parameters for the getAuthGrant method.

#	Name	Data type	Required	Description
1	accessToken	string	No	An access token is a string that is used to get the user data and a new session object.

note

If successful, this method also saves the user and session data to local storage and sets the Session header in Fetcher.

Sessions

note

Sign out a session​

note

Parameters​

note

Sign out from all sessions​

note

note

Sign out all except current​

note

Get current session​

Example response

Get user info from local storage​

Example response

Get user info from database​

Example response

note

Get all active sessions​

Example response

note

Invalidate session​

note

Clear local session data​

Set client session and user​

Set Client Session​

Parameters​

tip

Set User​

Parameters​

Get authentication grants​

Example response

Parameters​

note

Sign out a session

Parameters

Sign out from all sessions

Sign out all except current

Get current session

Get user info from local storage

Get user info from database

Get all active sessions

Invalidate session

Clear local session data

Set client session and user

Set Client Session

Parameters

Set User

Parameters

Get authentication grants

Parameters