API documentation for Iteras

    Server-side API

    To get information out of Iteras, you can call an Iteras server directly through HTTPS.

    The result is returned as JSON. In case of an error in the way the request is submitted (i.e. a programming or server authentication error), a response with a 40x HTTP status code is returned, e.g. 400 or 404.

    Authentication

    The authentication mechanism is currently a pre-shared key that you can find inside your account settings in Iteras.

    The preferred way to provide the key is by inserting a HTTP header X-Iteras-Key with the key as the value, e.g.

      X-Iteras-Key: 00aabbccddff112233445566778899

    If this proves difficult, you can also provide the key as the GET/query variable iteras-key, e.g.

      https://app.iteras.dk/api/customers/?id=12345&iteras-key=00aabbccddff112233445566778899

    Authenticate customer

    The /api/authenticatecustomer/ endpoint authenticates a given customer id/email + password combination.

    The endpoint supports POST only so you must post the parameters in the same manner as the browser, i.e. application/x-www-form-urlencoded.

    Since the Iteras server doesn't know the origin of the parameters provided, there is no intrinsic rate limit. Hence, if you connect an internet-facing application to this endpoint, you should put in a rate limit to prevent hacking by exhaustive search.

    The endpoint currently supports the following parameters - you must provide the password and either id or email:

    • "id" - customer/subscriber ID, e.g. id=12345

    • "email" - customer/subscriber email, e.g. email=somebody@example.com

    • "password" - customer/subscriber password, e.g. secret

    • "preauthseconds" - request a pre-authentication token valid for given seconds, e.g. 3600

    The data returned is an object with authenticated: true and the ID of the customer like this:

    {
      "authenticated": true,
      "id": "12345"
    }

    Or if authentication fails:

    {
      "authenticated": false,
      "errorcode": "unknowncustomer"
    }

    or

    {
      "authenticated": false,
      "errorcode": "invalidpassword"
    }

    If you specify preauthseconds, you'll get back a pre-auth token in the reply in case the user is authenticated, e.g.:

    {
      "authenticated": true,
      "id": "12345",
      "preauth": "Azxd123:JOIj123:JOjOIJASDF"
    }

    This token is only valid for the number of seconds you specified. When the pre-auth token is given to the iframe-generating JS API it causes the customer to be logged in automatically without being presented with a login screen:

      Iteras.selfserviceiframe({ profile: "myprofile", preauth: "Azxd123:JOIj123:JOjOIJASDF" })

    This is sometimes useful for making a single-signon site.

    Customer data

    The /api/customers/ endpoint enables you to retrieve customer/subscriber data.

    The endpoint uses GET and currently supports the following parameters, all optional:

    • "id" - a comma-separated list of customer/subscriber ids, e.g. ?id=12345,42312

    • "fields" - a comma-separated list of fields to return in the JSON, e.g. ?fields=data,subscriptions. The default is "data,active_subscriptions". You can choose between:

      • "data" - all fields directly on the customer, such as name and email address.
      • "active_subscriptions" - summary of currently active subscriptions
      • "subscriptions" - all subscriptions with information about periods, begin/end dates and products received in each period

    If you don't specify any parameters, you'll get information on all customers.

    The data returned is an object with an array of customer information (possibly empty array), like this:

    {
      "customers": [
        {
          "id": "12345",
    
          "data": {
            "name": "Test Person",
            "email": "someone@example.com",
            "address": "Test Person\nRådhuspladsen 2, 3. th.\n1550 København V\nDenmark",
            "location": "Rådhuspladsen 2, 3. th.\n1550 København V",
            "country": "Denmark",
            "country_code": "DK",
            ":Custom field": "Some value"
          },
    
          "active_subscriptions": [
            {
              "campaign_name": "3 issues",
              "campaign_id": "3i"
            }
          ],
    
          "subscriptions": [
            {
              "data": {
                ":Custom subscription field": "Value here"
              },
              "periods": [
                {
                  "campaign_name": "3 issues",
                  "campaign_id": "3i",
                  "begin": "2010-12-24T12:00:00",
                  "end": null,
                  "products": [
                    {
                      "name": "Name",
                      "date": "2011-12-26",
                      "external_id": "External ID"
                    }
                  ]
                }
              ]
            }
          ]
    
        },
    
        ...
      ]
    }

    Note that Iteras internally has more processing information about the customers. If you need more than what's currently available, please contact us.

    Javascript API

    The Javascript API allows you to integrate Iteras functionality directly into another site. To get access to the API, include https://app.iteras.dk/static/api/iteras.js in your page, as in

      <script src="https://app.iteras.dk/static/api/iteras.js" type="text/javascript"></script>

    Then you can call various methods on a global Iteras object, e.g.

      <script>
        document.write(Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXX" }));
      </script>

    Iframes

    There are a bunch of methods for generating iframes to be included on your site. Common parameters are:

    • "profile" which is a short lower-case descriptive string to use for the URL, e.g. if your business entity name is "Foo Bar" it will typically be "foobar"; you can find it in your settings inside Iteras.
    • "cssclass" which sets a CSS class on the body element inside the iframe, in case you need to customize a particular iframe.
    • "preauth" which given a pre-auth token causes a given customer to be logged in automatically.

    Subscriber self-service iframe

      Iteras.selfserviceiframe({ profile: "myprofile" })

    Generates an iframe with the subscriber self-service pages. The first page will be a login page.

    Ordering form iframe

      Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXXX" })

    Generates an iframe with an ordering form. "orderingid" is the URL id for the ordering form inside Iteras (it’s usually either a randomly generated string or something descriptive that you have chosen).

    Paywall login iframe

      Iteras.paywalliframe({ profile: "myprofile", paywallid: "XXXXXX", next: "/" })

    Generates an iframe with login to the paywall. The paywall id can be found in the paywall settings. "next" is a path to redirect to upon succesful login in case there isn’t a more appropriate redirect known (the iframe looks for an iterasnext GET parameter in the page it is inserted.

    The paywall login page uses the iframe to set a cookie on your domain with paywall access info - see the paywall section for details.

    Note that paywall login iframe is intended to redirect to another page. If you don't give it redirection information or just somehow redirect to the same page so it is rerendered, it will show the login form again. Don't get confused! If your browser has the cookie, you're logged in.

    You can set the required access level with "access" (see the paywall section for more info), e.g.

      Iteras.paywalliframe({ profile: "myprofile", paywallid: "XXXXXX", access: "user" })

    In case you need to login to multiple paywalls at the same time, e.g. if each paywall walls off a separate section, you can specify a list of paywall ids instead of a single id, e.g.:

      Iteras.paywalliframe({ profile: "myprofile", paywallid: ["XXXXXX", "YYYYYY"], next: "/" })

    Inserting an iframe

    The iframe methods generate a string with HTML that you can either insert directly in the page with document.write, e.g.

      <script>
        document.write(Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXX" }));
      </script>

    or you could use a framework, e.g. with jQuery

      <div id="ordering-iframe-container"></div>
      ...
      <script>
        $(function () {
          $("#ordering-iframe-container").append(Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXX" }));
        });
      </script>

    The iframe will automatically resize its height based on the height of its content. Note that for this to work, the iteras.js script must be included on the page (as would normally happen when you use the API).

    If you want to control the height or width yourself, we recommend you put the iframe (or document.write <script>) inside an element you control yourself and set max-width/max-height on that with CSS. This prevents conflicts with the styles applied by the Iteras API.

    Common questions/problems

    The iframe has sizing problems/looks weird?

    It’s common to end up with a bunch of CSS files to style various things. There is probably something in one of those files with a rule that accidentally applies to the Iteras iframes. Rules to look out for are both rules on iframes and rules on the parent elements of the Iteras iframes, e.g. if the iframe doesn’t automatically increase its height, there could be a rule that restricts the max height of the elements where the iframe is embedded.

    To debug this, inspect the inserted iframe with the developer tools in your browser and see what rules are applied to the element and its parents.

    How do I control the style of the iframe itself, e.g. width/height?

    Don’t. Put it inside a wrapper element (e.g. a <div>) and apply your styles to that element. This prevents conflicts with the styles applied by the Iteras API.

    How do I control the looks of the iframe contents?

    Due to separate security contexts in the browser, the iframe content ignores outside rules. So you have to include your CSS through the website customization fields in the customer service settings inside Iteras. You can include the styles inline or through a link to a CSS file hosted on your own site.

    How do I apply different styles for different iframes?

    Use the "cssclass" parameter when generating the iframe, it sets a CSS class on the body element inside the iframe so you can the hook up on that.

    Paywall

    The paywall works the way that visitors are denied access unless they have a pass cookie called "iteraspass" that authorizes them. This cookie is set (on your domain) by the paywall login iframe upon successful login and is normally valid for an extended period of time.

    This design minimizes the coupling between your system and Iteras. Visitors do not depend on access to an Iteras server to view content besides the initial login, improving fault tolerance and response times.

    In order to protect against subscriptions running out or being stopped, the pass cookie should be regenerated from time to time by Iteras - if the check fails, the cookie is deleted so the user is denied access.

    To get started, you need to add a paywall inside Iteras and configure its settings there. This gives you a paywall id for use in the API.

    How to use the paywall

    To setup a basic paywall you need to setup a landing page for people who are not logged in. On this page, you’d normally include an explanation that paywall access is required, a strong call to action for people who have not signed up yet and either the paywall login iframe or a link to a page with it.

    Say the path to your landing page is "/paywall/landing.html", then you simply call

      Iteras.wall({ paywallid: "XXXXXX", redirect: "/paywall/landing.html" })

    on all pages you want paywalled. This call checks that a cookie with the right paywall id exists, if not it redirects to the URL given by "redirect". In case you need to check for a pass to either of a number of paywall ids, put in a list, like this

      Iteras.wall({ paywallid: ["XXXXXX", "YYYYYYY"], redirect: "/paywall/landing.html" })

    The call to Iteras.wall will also automatically regenerate the cookie from time to time by contacting the Iteras server.

    The landing page may get some query/GET parameters starting with "iteras", e.g.

    http://www.example.com/paywall/landing.html?iterasnext=...&iterasaccess=...

    These are read by the paywall login and ordering iframes, so if you don’t have the iframes embedded directly in the landing page but instead accessible through links, you should append all query parameters starting with "iteras" to those links. Otherwise, visitors will have reduced functionality, e.g. people will not be redirected back to the original page upon logging in.

    Logging out of the paywall

    To log out from the paywall, call

      Iteras.logoutFromWall()

    e.g.

      <button id="logout">Log out</button><
    
      <script>
        document.getElementById("logout").onclick = function () {
          Iteras.logoutFromWall();
        };
      </script>

    Upon completing the log out, by default the page will be reloaded. You can redirect to another page by specifying a redirect option, like this

      Iteras.logoutFromWall({ redirect: "/some/url" })

    You can also specify redirect: null to prevent the reload.

    Custom paywall handling

    In case you need something else than a redirect upon un-authorized access, you can provide an "unauthorized" callback to the Iteras.wall function instead of the "redirect" parameter, like this

      function myPaywallHandler() { ... }
      Iteras.wall({ paywallid: "XXXXXX", unauthorized: myPaywallHandler })

    Note that the wall function may call the handler or return immediately and call the handler later. The latter may for instance happen in case the pass cookie is regenerated (which may take some milliseconds) and it turns out the visitor no longer has access.

    If you omit both "redirect" and "unauthorized", nothing will happen in case of an unauthorized visitor, but the code will still check the pass cookie from time to time and delete it if it is no longer valid.

    Access levels

    There are currently two access levels in Iteras.

    • Visitors with active subscriptions (on campaigns with digital access) are at the "sub" level.
    • Visitors registered as subscribers but with no active subscriptions are at the "user" level.

    It is sometimes useful to give the user-level visitors access to selected areas so you can configure Iteras to hand out paywall passes to them, and then add the "access" parameter to the wall function, like this

      Iteras.wall({ paywallid: "XXXXXX", redirect: "/paywall/landing.html", access: "user" })

    for user-accessible pages and

      Iteras.wall({ paywallid: "XXXXXX", redirect: "/paywall/landing.html", access: "sub" })

    for pages for the actual subscribing subscribers.

    Paywall pass cookie

    The paywall pass cookie consists of a number of fields separated by | with a signature at the end beginning with /, e.g.

    sub|n8fsoupukhv3|2016-01-23T12:35:29Z|31168|123.123.123.123/sha256:596c625c185499e6a4394dbcec8713347ba7d0e67acb1fe3fe876f424f35bfc7

    The fields can’t contain | or other characters not allowed in cookies so a simple string split can be used for parsing. The fields are currently:

    • access level - in case of multiple paywall ids, the level for each paywall is separated with a comma in the same order as the paywall ids in the next field
    • paywall id - in case of multiple paywall ids, they are separated with a comma, e.g. XXXXX,YYYYY
    • UTC timestamp for when the pass expires (normally requiring new login)
    • subscriber id
    • IP address of other end when pass was granted

    You can count on the ordering of the fields, but we might add more fields at the end in the future so don’t write code that assumes that the number of fields is fixed.

    The signature is everything to the right of the last / in the pass and consists of a signing algorithm identifier followed by : followed by the actual signature. The signing algorithm is run on everything to the left of the /.

    "sha256" means HMAC SHA256 with hexadecimal numbers as output (this is a standard algorithm with implementations in many programming environments). The key used for the HMAC is the API key you can find in the settings inside Iteras.

    The signature is not checked in the JS API, but you can use it server-side to ensure that the cookie was actually generated by Iteras.

    Security concerns

    Note that the JS API here as a client-side solution allows sufficiently skilled people to trick the paywall.

    The only way around that is a server-side check of the pass cookie that prevents any content to be sent to people without a cookie. But as long as it is difficult enough to circumvent the paywall for 99.9% of your target audience (including on commodity hardware like tablets), you may find it cost-ineffective to try to prevent the possibility of a few cheaters.