Session tokens

Session tokens are the only means of authenticating embedded (iframe) applications, due to 3rd party cookie restrictions on modern browsers.

A session token authentication mechanism can be summarized as follows:

  • Your embedded application makes a request for a session token via the Mantle app bridge (postMessage to a window with a different host)
  • Mantle responds (via postMessage back to your application's window) with a session token. A session token is a JWT, generated by Mantle, that contains information about the current user, and organization
  • The session token is signed by Mantle with the organization's access token.
  • The extension forwards along this session token to its back-end in place of any cookies or traditional browser authentication mechanisms.
  • The back end verifies the session token JWT forwarded along by the client, from Mantle, and using the shared secret can assert that the user and organization described in the JWT payload are in fact coming from Mantle.
  • The application can consider this request authenticated, and respond in turn with whatever user and organization specific data it may have

Note: JWTs have a short expiry (1 minute), so make sure to request new session tokens from the Mantle app bridge on a regular basis before making follow up requests from your front end.

Session tokens are not access tokens

Access tokens are for your back-end to interact with Mantle's Core API, whereas session tokens are used to authenticate front end requests coming from your embedded application.

access tokens - are for server-to-server communication

session tokens - are for front end to your back end communication

React.js example