Introduction

Baselayer allows partners and resellers to autonomously generate profiles for their customers, maintain customers’ data separated, and correctly associate each request with each end user.

This guide serves as a reference point for the implementation of Baselayer across your customer base.

Concepts

• Federation: Institution overseeing the product and integrating directly with Baselayer
• Organization: End customer, who reviews Baselayer results via the partner/reseller
• Application: Environments available for each Organization, each application has its unique API key. Usually 2: production and sandbox (used for testing)

Initial Set-Up

Baselayer will provide you with your federation_id, an initial Federation API key, and access to the dashboard. An initial organization, with the same name as the federation, will also be created immediately.

Once in the platform, you can click on “My Federation” to access the list of existing organizations, the Federation users, and the Federation API keys.

All actions to manage your API keys, including creating new keys or deleting existing ones, can also be completed via the available API routes.

Creating an Organization

To start serving a new customer, you can create a new Organization in the platform or making a POST/organizations request to the API - using your Federation API keys.

There are only 4 fields in the process of creating an Organization:

• name (required): name of the organization
• domain_name (optional): email domain associated with the organization
• type (required): type of organization, this field is very relevant for Baselayer’s data quality and personalization, and has a defined set of options
• external_id (optional): some of our customers require an internal id to be attached to the profile of each customer for identification purposes - this field is available for that goal

In case of the API request, you will receive a http_201 code in case of a successful response, http_422 in case of a validation error, or http_409 in case the name and/or external_id already exist under your Federation.

Authentication Methods

Any API request at an organization level can be initialized with the Organization's dedicated API keys, or with the Federation API key adding headers.

In the following section we will explore the latter option:

Header: external_id

This is the preferred methodology.

When using Federation API keys, include the Organization's external_id in your request headers:

X-External-ID: \<external_id>
  

In case of a request to the sandbox environment, you should include the following as a header:

X-External-ID: \<external_id"-sandbox">
  

Header: organization_id

For organization-level tasks such as adding, amending or deleting members, or using GET/organization, you can instead use the organization_id:

X-Organization-ID: \<organization_id>
  

For application-level tasks (such as a business search or any other API requests), you should apply the following two headers to ensure the correct application (production or sandbox) is selected:

X-Organization-ID: \<organization_id>
X-Application-ID: \<application_id>
  

A user could retrieve both fields under the GET/organizations{organization_id} route, using the Federation API keys.

Users

Federation Members

Employees of Baselayer’s partners need to be added directly as “Federation Users”. This will enable them to seamlessly access every organization under the Federation.

You can do so under the menu “My Federation” mentioned above, or via API through the routes available under /federations/{federation_id}/members.

Organization

Users of the end customer should be added as part of their specific Organization. Organization users will only be able to access their own dashboard, and only review the cases that were run by their organization.

To perform this action, you can click on “My Organization” in the top-right menu and add them as a new team member.

You can also add a new organization member via API through POST /organizations/{organization_id}/invitations. You could use the Organization API keys, or the Federation API keys adding X-Organization-ID as a header (explained previously under Authentication Methods).