Query String Parameters Overview

This article provides a guide for customers and CRM integrators who wish to launch Archiver wrapped inside an iframe or as a popup window from a CRM module or other external system.

Archiver can be invoked with specific URL query string parameters that can be used to prepopulate the main page with search results triggered from data within the external system (for example from a customer email address or loyalty number that may be pulled up as a current record within a CRM tool).

Launching Archiver with Query String Parameters

The sequence of steps for launching Archiver with query string parameters are:

Authenticate against the Archiver API, using a username and password, via the login endpoint. Successful authentication will return an authentication token.
Compose the URL that will be used to populate the iframe or popup window. This URL will contain the Archiver http endpoint, and query string parameters including the authentication token and email search parameters.
Launch the popup window or iframe using the URL.

Client-Side and Server-Side Code

It is important to differentiate between server-side code and client-side code.

Server-side code is hidden from the user and runs on the server for the system being used to launch Archiver.
Client-side code is typically run inside of a web page, iframe, or popup window, and is available for the user to see (even if it’s difficult, it’s usually possible for someone who is determined).

For the purposes of the application described in this document, the authentication should be considered server-side code, and the popup window or iframe containing the Archiver search results should be considered client-side code.

It is important that usernames and passwords are never available or used in client-side code. This is why the authentication step described in this document should always be done on the server-side. It would be possible to do this style of authentication on the client-side, for example, in Javascript running on a web page, but to do so would pose as a security risk, because the email and password used in the authentication would be available to a user who was determined to find them.

Authentication

Authentication is performed by making a REST style call to the authentication endpoint, passing an email address and password. This authentication step should always take place on the server-side.

Service URL:

post	/api/v1/email/login

The service URL will depend on whether your Archiver account is hosted within the US or EU. Please ask your Sageflo Account Manager if you are not sure which to use.

Request Method:

Post

Request JSON:

{
  "email": "<LOGIN_EMAIL>",
  "password": "<PASSWORD;",
}

You will use the email and password provided to you by your Sageflo account manager in the request JSON.

HTTP Status Code:

The API will return a status code of 200 for a successful request and 401 for a failed authentication.

Request JSON:

{
  "auth_token": "<AUTH_TOKEN>",
  "issued_at": "<TIMESTAMP;",
}

The attributes in the response are:

auth_token: The authorization token to be used in the URL that will populate the iframe or popup window with Archiver email search results.
issued_at: A timestamp for when the token was issued.

The authorization token returned by the login method is a JWT token (JSON Web Token). It contains credentials that the Archiver application uses to grant access to certain resources. It is securely signed with a secret key using SHA256 to verify the sender of the token, and so that it cannot be modified or recreated by a third party. You can learn more about JWT here: https://jwt.io/introduction/.

The token can be reused for up to 2 hours after a successful authentication.

Constructing the Archiver Search URL

Base URL:

The base URL will depend on whether your Archiver account is hosted within the US or EU. Please ask your Sageflo Account Manager if you are not sure which to use: