---

SBS is a multi-tenant, multi-application, cloud API provider. It was built with the following key concepts in mind:

In SBS, these three concepts roughly translate into the following structure:

The Account, Application, and Tenant entities are the pillars of SBS architecture and are all managed from a Web application called the “SBS Console”. Let’s examine these entities one by one.

SBS Account

To use Socrate Business Services, your organization requires an SBS account.

An SBS account groups together all the API keys and other high-level SBS settings that your organization defines. The SBS account also acts as a billing point for usage of SBS services.

Application

An application is technically an API client that calls the SBS APIs. It may be a purely virtual application that does not actually exist in the real world or it may refer to some actual piece of software that your organization has. For example, your organization may have a website, a desktop app, and a mobile app that all need to call Socrate Business Services APIs. From the SBS perspective, these are all applications, and they should all be defined as such under your organization’s SBS account.

The main purpose of applications is to group together various configuration settings that are meaningful at that level. For example, if you intend to use the Email Service and allow integration with OAuth 2.0 providers such as Google or Azure, then the respective OAuth 2.0 client secrets are defined at application level. Likewise, if you intend to use the e-Factura Service, the OAuth 2.0 secrets for access to the Romanian Tax Authority API are defined at application level.

The settings defined at application level affect all the API callers using that application (let’s call them tenants).

Tenant

A tenant is an entity that consumes the SBS API. A tenant is typically some organization that has licensed your SBS-driven application, although it may also be a physical person.

A tenant is important in terms of API usage. As you will see next in this tutorial, each call to the SBS APIs requires an API access key known as a “service access key”. A service access key is always associated with a specific application and tenant that makes the call.

All your organization’s customers should be added as tenants in SBS, if they need to call SBS APIs from any of your applications. That’s because a tenant is an API consumer, which may be important for tracking API usage and for billing purposes.

To put it simply, you need to create at least one tenant to call the SBS API. If your organization does not need to segregate API usage by tenant and just needs to consume the SBS APIs for its own purpose, you still need to create at least one tenant. This tenant will identify your organization as a consumer of the SBS API within the realm of your SBS account.

Service Access Key

To call an API, you typically need some form of authentication, like a token or a service access key. SBS provides access to its APIs based on service access keys or tokens. Service access keys are suitable for use in back-end applications, while tokens are more appropriate for browser-based applications.

A service access key uniquely identifies your application and your application’s tenant to the API.

This means that, when you generate a service access key, you must specify the application and tenant for which you are generating it. In other words, you can generate service access keys for each unique application-tenant combination that may possibly exist in your SBS account.

As illustrated in the diagram, each service access key originates from a particular application and tenant, and each API call requires a service access key. The major benefit of such setup is that API data is isolated to that particular app and tenant combination only. Likewise, API usage can be tracked down to that particular application and tenant combination only.