Skip to main content

B2B2C - License Keys

A B2B2C partnership allows an organization to generate license keys, which can be redeemed by Leah users to obtain access to different tests.

B2B2C licenses are granted by means of a license key. The organization defines the products to which it will grant access and will deliver the keys to the desired users. These licenses are cumulative. That is, a user can redeem as many licenses as may suited, as long as they are issued by the same organization.

The creation of the license keys is done through the partnership API.

Partnership API​

To use the partnership API, you need a secret key and an identifier known as partnerId. This data is provided by the Leah developer or agent who manages your partnership.

Once you have the credentials (Staging or Production), you can proceed to use the API. The documentation for the partnership API can be found at swagger:

Swagger documentation: https://staging.api.leahapp.com/partners/docs

tip

In the swagger documentation, all mandatory fields and expected behaviors are specified according to the data that can be send. It is recommended to carefully read the information in each field on each endpoint.

Create license keys​

When creating license keys, there are several ways to grant users access to use Leah products. The way a user can redeem their license and sign in to Leah depends on how the license key is created. You can grant the user access via email, require sign in via an IdP, or redirect the user to Leah after acquiring the license from an organization-owned platform (e.g. from an eCommerce site).

The possible scenarios for creating a license are described below. Choose carefully which scenario best suits your users.

License keys and sign in with an IdP​

This option allows you to create license keys and ensure the users sign in through your own IdP using SAML.

Prerequisites:

  1. Integration for sign in through an IdP with SAML.
  2. Access to the partnership's API.
  3. Ensure that the emails of the users to be invited to Leah are valid.

Once the requirements are met, licenses can be created to be redeemed only by users from the organization's SAML IdP. The API returns the access URL to redirect the end user.

Optionally, the end users could be invited via email to sign in to Leah (request this feature to the Leah agent who manages your partnership).

For example, you can create a license that will be used by an IdP user like this:

create-license-saml.js
const http = require("http");

const options = {
  "method": "POST",
  "hostname": "api.leahapp.com", // Or staging.leahapp.com for testing
  "path": "/partners/<PARTNER_ID>/licenses", // Replace <PARTNER_ID> with your partnerId
  "headers": {
    "accept": "application/json",
    "Authorization": "Bearer <SECRET>", // Replace <SECRET> with your secret
    "Content-Type": "application/json",
    "Content-Length": "225"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    const jsonBody = JSON.parse(body.toString());

    console.log("License key", jsonBody.key);
    console.log("URL to access Leah", jsonBody.accessUrl);
  });
});

req.write(JSON.stringify({
  externalId: 'random-external-id',
  products: [{id: 'diagnostic_test', quantity: 2}, {id: 'speaking_test', quantity: 2}],
  email: 'johndoe@example.com', // Required
  lng: 'es'
}));
req.end();
warning

The email address is required, but it's only used to send the optional invitation. In this case, the license is not tied to the provided email. The license key can be redeemed by any user accessing through the IdP.

License keys and sign in with Leah​

This option allows you to create license keys for users who will need to complete their registration in Leah, using their email address and creating a password.

Prerequisites:

  1. Access to the partnership's API.
  2. Ensure that the emails of the users to be invited to Leah are valid.

Once the requirements are met, licenses can be created to be redeemed only by Leah users who complete their registration. Upon their first sign in, they will be asked to add a password so they can redeem the license key and sign in to Leah in the future. The URL to redirect users to complete their registration and use their licenses is returned in the API response.

Optionally, the end users could be invited via email with instructions to sign in to Leah (request this feature to the Leah agent who manages your partnership).

For example, you can create a license that will be used by a Leah user like this:

create-license-user-and-password.js
const http = require("http");

const options = {
  "method": "POST",
  "hostname": "api.leahapp.com", // Or staging.leahapp.com for testing
  "path": "/partners/<PARTNER_ID>/licenses", // Replace <PARTNER_ID> with your partnerId
  "headers": {
    "accept": "application/json",
    "Authorization": "Bearer <SECRET>", // Replace <SECRET> with your secret
    "Content-Type": "application/json",
    "Content-Length": "225"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    const jsonBody = JSON.parse(body.toString());

    console.log("License key", jsonBody.key);
    console.log("URL to access Leah", jsonBody.accessUrl);
  });
});

req.write(JSON.stringify({
  externalId: 'random-external-id',
  products: [{id: 'diagnostic_test', quantity: 2}, {id: 'speaking_test', quantity: 2}],
  user: {name: 'John', lastName: 'Doe', email: 'johndoe@example.com'} // Required
  lng: 'es'
}));
req.end();
warning

The user information is required to pre-register the user account. The license key can only be redeemed by the specified user.

License keys without user restrictions​

This option allows you to create license keys that can be redeemed by any user in Leah. Unlike the previous options, this type of license key does not have any user or IdP sign in restrictions.

Prerequisites:

Once the requirements are met, licenses can be created to be redeemed by any Leah user. The license key can be obtained from the API response to be delivered to the user, or you can use the Leah access URL that is returned in the API response to redirect the user.

For example, an unrestricted license can be created like this:

create-license-no-restrictions.js
const http = require("http");

const options = {
  "method": "POST",
  "hostname": "api.leahapp.com", // Or staging.leahapp.com for testing
  "path": "/partners/<PARTNER_ID>/licenses", // Replace <PARTNER_ID> with your partnerId
  "headers": {
    "accept": "application/json",
    "Authorization": "Bearer <SECRET>", // Replace <SECRET> with your secret
    "Content-Type": "application/json",
    "Content-Length": "225"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    const jsonBody = JSON.parse(body.toString());

    console.log("License key", jsonBody.key);
    console.log("URL to access Leah", jsonBody.accessUrl);
  });
});

req.write(JSON.stringify({
  externalId: 'random-external-id',
  products: [{id: 'diagnostic_test', quantity: 2}, {id: 'speaking_test', quantity: 2}],
  lng: 'es'
}));
req.end();
warning

In this case, the license does not have any restrictions. The license key can be redeemed by any user.

Redeem license keys​

The creation of the key and how it is delivered to the end user is up to the organization and is done solely through the partnership API.

For example, in a scenario where an organization sells access to Leah's tests in a proprietary eCommerce, the process would look like this:

tip

You can use the SAML integration to allow eCommerce users to log in to Leah Web without having to go through registration.