Skip to main content

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 Agnost client library, you can manage sessions of your application users. Below is the list of session management capabilities of Agnost that you can use in your service designs.

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.

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

Parameters​

Here you can find parameters for the signOut method.

#

Name

Data type

Required

Description

1sessionTokenstringNoA 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.

// Sign out all sessions
const { errors } = await agnost.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.

//Sign out all sessions except current
const { errors } = await agnost.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.

// Get current session
const session = agnost.auth.getSession();
Example response
{
  "userId": "6233247fb46a9b5bb144e797",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IhJmslSKnS2H7kpX...",
  "creationDtm": "2022-03-16T19:36:27.739Z",
  "userAgent": {
    "ua": "",
    "browser": {
        "name": "",
        "version": "",
        "major": "" 
    },
    "engine": {
        "name": "",
        "version": ""
    },
    "os": {
        "name": "",
        "version": ""
    },
    "device": {
        "model": "",
        "type": "",
        "vendor": ""
    },
    "cpu": {
        "architecture": ""
    }
  }
}

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.

//Get current session
const user = agnost.auth.getUser();
Example response
{
  "_id": "6233247fb46a9b5bb144e797",
  "provider": "agnost",
  "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.

//Get current session
const result = await agnost.auth.getUserFromDB();
Example response
{
  "user": {
    "_id": "6233247fb46a9b5bb144e797",
    "provider": "agnost",
    "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.

//Get all sessions of the user (active or not)
const result = await agnost.auth.getAllSessions();
Example response
{
  "sessions": [
    {
      "userId": "6233247fb46a9b5bb144e797",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "creationDtm": "2022-03-17T13:17:50.903Z",
      "userAgent": {
        "ua": "",
        "browser": {
            "name": "",
            "version": "",
            "major": "" 
        },
        "engine": {
            "name": "",
            "version": ""
        },
        "os": {
            "name": "",
            "version": ""
        },
        "device": {
            "model": "",
            "type": "",
            "vendor": ""
        },
        "cpu": {
            "architecture": ""
        }
    },
    {
      "userId": "6233247fb46a9b5bb144e797",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX...",
      "creationDtm": "2022-03-17T13:23:52.882Z",
      "userAgent": {
        "ua": "",
        "browser": {
            "name": "",
            "version": "",
            "major": "" 
        },
        "engine": {
            "name": "",
            "version": ""
        },
        "os": {
            "name": "",
            "version": ""
        },
        "device": {
            "model": "",
            "type": "",
            "vendor": ""
        },
        "cpu": {
            "architecture": ""
        }
    }
  ],
  "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. 

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

If signInRedirect is specified in ClientOptions when creating the Agnost 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 Agnost 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.

//Deletes locally saved session and user data
agnost.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.

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

Parameters​

Here you can find parameters for the setSession method.

#

Name

Data type

Required

Description

1sessionSessionNoA session of the user is an object that contains the following properties: userId, token, creationDtm, userAgent.
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.

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

Parameters​

Here you can find parameters for the setUser method.

#

Name

Data type

Required

Description

1userUserNoA 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.

//...You can get user and session data using the accessToken
const result = await agnost.auth.getAuthGrant(accessToken);
Example response
{
  "user": {
    "_id": "6235e0eb25de47092f4d5300",
    "provider": "agnost",
    "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...",
    "creationDtm": "2022-03-16T19:36:27.739Z",
    "userAgent": {
      "ua": "",
      "browser": {
          "name": "",
          "version": "",
          "major": "" 
      },
      "engine": {
          "name": "",
          "version": ""
      },
      "os": {
          "name": "",
          "version": ""
      },
      "device": {
          "model": "",
          "type": "",
          "vendor": ""
      },
      "cpu": {
          "architecture": ""
      }
    }
  },
  "errors": null
}

Parameters​

Here you can find parameters for the getAuthGrant method.

#

Name

Data type

Required

Description

1accessTokenstringNoAn 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.