Conventions
Each service described in this chapter includes an “Access Info” table. This table provides the endpoint (URL) where the service is accessible, as well as the type of service access keys that the service accepts.
Access keys
To access any SBS service, you need access keys. Access keys are strings that you must provide in the x-api-key HTTP header of the request in order to be able to make API calls.
Depending on the data you want to access (tenant-level, app-level, or even account-level), access keys can be of the following types:
- Service access key (SAK) - This key is used to retrieve data at tenant level. More precisely, the bearer of the key can access API data for a specific app and for a specific tenant. Each key uniquely identifies a tenant-app combination. Consequently, in order to provide all your tenants with separate service access keys, you must generate a service access key for each tenant-app combination within your SBS account. For an example of how to generate and use a service access key, see Generate a service access key.
- App-level service access key (ALSAK) - This key is required for scenarios when the key bearer needs access to app-level data. As illustrated in the table below, there are certain services that provide or modify data at app-level, and consequently you must use an app-level access key in that case.
- Account access key (AAK) - This key provides access exclusively to the Account API. The Account API enables you to perform programmatically the same SBS entity management actions that are available in the graphical user interface of the SBS Console. For example, such a key is useful if you have to create thousands of tenants (and their respective service access keys) and would like to do this programmatically.
Each key has a scope. Scope is a security mechanism which makes it possible to grant or deny access to various areas of the SBS API. You can set the scope to be as generic or as specific as needed by your business case. For example, when generating a service access key, you can limit its scope only to a specific service, or only to specific queries or mutations within a service. For more information, see Restrict access to services.
The following table lists the keys accepted by each service.
Date and time conventions
The following date-specific conventions apply to all services:
-
All date and time references across SBS are in the GMT time zone, unless specified otherwise in the description of each field.
-
Many services provide filters where you can supply a “from” and “to” date as input. Importantly, the “from” and “to” values may be of type
DateorDateTime.If “from” and “to” are of type
Date, then the “to” date is inclusive. For example, the filter{ "createdAt": { "from": "2024-01-01", "to": "2024-01-02", } }will return data created on 2024-01-01 and also on 2024-01-02.
However, if “from” and “to” are of type
DateTime, and if you supply only a date value without time, the time is implicitly considered to be 00:00:00. This means that the filter{ "createdAt": { "from": "2024-01-01", "to": "2024-01-02", } }will NOT return data created on 2024-01-02. To retrieve this data as well, make sure to supply the to time value explicitly, for example:
{ "createdAt": { "from": "2024-01-01", "to": "2024-01-02T23:59:59.999Z", } }