1. Home
  2. Sesam Hub
  3. Documentation
  4. Service API

Service API

Introduction

Sesam provides a RESTful API for controlling the service and for working with the data in the datahub.

If you follow the Getting started guide, the api will be served on the url you find on the management studio “settings” page under the “Connection url” heading. For a cloud instance it will typically be on the form https://instance-guid.sesam.cloud/api.

All references to this URL in this document should be substituted with the real URL for your Sesam instance. The rest of this document will assume that the api can be found on this URL.

The API documentation is also self-hosted and can be explored using the Swagger user interface at “<host:port>/api/reference”.

Most API calls will require you to authenticate using a JWT token .

You can also use a commandline tool like curl or wget to explore the API. This will be the most useful approach if you are planning to communicate with Sesam using a script or a program.

When using curl to access the API url’s directly, you will need to supply the JWT token for each HTTP request. Here’s an example that creates an alias for curl that does this for you (remember to change the example URL to your real sesam instance URL):

# Create a text-file with the email and password you use to log in to Sesam:
echo "email=YOUR_EMAIL_ADDRESS&password=YOUR_PASSWORD" > cred.txt

# Download the authorization token for the specified email and password and store it in an environment variable:
export SESAM_AUTH_HEADER="Authorization: Bearer $(curl -d @cred.txt https://instance-guid.sesam.cloud/api/jwt)"

# Make an alias to run curl with the authorization token:
alias curlJWT='curl -H "$SESAM_AUTH_HEADER"'

You can then substitute curl with curlJWT in all calls to the API. The rest of this document assumes that you have created this alias.

Note that if you are communicating with the API using your own program or script, you must remember to set the HTTP header property “Authorization” to the string “Bearer ” concatenated with the token you get from the command:

curl -d @cred.txt https://instance-guid.sesam.cloud/api/jwt

This was built-in to the shell script snippet we used to set up the culrJWT alias previously; the “cred.txt” file contains the text “email=YOUR_EMAIL_ADDRESS&password=YOUR_PASSWORD” without the quotes and substituted with your real username and password. For security reasons, remember to remove the cred.txt file after you have retrieved the JWT token.

The most important api urls are:

/api/pipes (i.e. https://instance-guid.sesam.cloud/api/pipes)

This returns a list of pipes. For an explanation of what a pipe is, read the Pipes concept definition.

/api/datasets (i.e. https://instance-guid.sesam.cloud/api/datasets)

This returns a list of datasets. (For an explanation of what a dataset is, read the Datasets concept definition).

For a full description of the /pipes and /datasets endpoint, read the “Pipes” and “Dataset” sections in the Instance API Reference.

Examples

In the following we will go through a few examples of what you can do with the api. As mentioned previously, we will use the curlJWT alias we created to interact with the api from the command line. If you are using MS Windows you can install for instance Cygwin in order to install and use the curl command (and create the curlJWT alias).

Get a list of all the pipes

With curl:

curlJWT https://instance-guid.sesam.cloud/api/pipes

Get information about one specified pipe

To only get one specific pipe, add the pipe’s “_id” attribute to the pipes-url. To get the pipe with the _id “Northwind:Products”, you would do this:

With curl:

curlJWT https://instance-guid.sesam.cloud/api/pipes/Northwind:Products

Run operations on a pipe

A pipe typically has a number of operations that can be triggered via the api. These are listed in the pipeinfo[“runtime”][“supported-operations”] attribute. A typical value looks like this:

"supported-operations": [
            "enable",
            "disable",
            "start",
            "stop"
        ]

These operations are triggered by sending a POST-request to the url /pipes/{pipeID}/pump. For example: to disable the “Northwind:Products” pipe you would do this:

With curl:

curlJWT --data operation=disable https://instance-guid.sesam.cloud/api/pipes/Northwind:Products/pump

To manually start the pipe’s pump, you would do this:

With curl:

curlJWT --data operation=start https://instance-guid.sesam.cloud/api/pipes/Northwind:Products/pump

sesam start-pump Northwind:Products --server_base_url https://instance-guid.sesam.cloud/api

To stop a running pump, you would do this:

With curl:

curlJWT --data operation=stop https://instance-guid.sesam.cloud/api/pipes/Northwind:Products/pump

Get a list of all the datasets

With curl:

curlJWT https://instance-guid.sesam.cloud/api/datasets

Get information about one specific dataset

To only get one specific dataset, add the dataset’s “_id” attribute to the dataset-url. To get the dataset with the _id “Northwind:Products”, you would do this:

With curl:

curlJWT https://instance-guid.sesam.cloud/api/datasets/Northwind:Products

Get the content of the dataset

To see the entities in the dataset, add “/entities?limit=3” to the dataset’s url, like this:

With curl:

curlJWT https://instance-guid.sesam.cloud/api/datasets/Northwind:Products/entities?limit=3

The “limit” parameter limits the number of returned entities to a managable number. Without this parameter, all the entities in the dataset would be returned. Depending on the size of the dataset, that could take a while, so it is generally a good idea to include a “limit”-parameter.

Get the content of the dataset as SDShare

To see the entities in the dataset as a SDShare feed, add “/sdshare-fragments” to the dataset’s url, like this:

curlJWT https://instance-guid.sesam.cloud/api/datasets/Northwind:Products/sdshare-fragments

Parameters such as limit also apply to this URL.

The corresponding SDShare collection feed is available from:

curlJWT https://instance-guid.sesam.cloud/api/datasets/Northwind:Products/sdshare-collection

This collection feed URL is usually the URL you need to supply in a SDShare client.

Note that for the conversion of the entities to RDF to work, the entities must either:

  1. be pre-processed to consists of full URIs for all properties (including the _id property)

or:

  1. be pre-processed to CURIEs form AND the dataset id need to be registered as en entry in the RDF registry with appropriate prefix settings and prefix rules.

See Working with RDF for more information on how to prepare your data for RDF output.

Instance API Reference

GET /models

EXPERIMENTAL: Returns a list of all the models

Query Parameters

  • effective (boolean) – If true then implict and explicit models will be merged in the response.

  • verbose (boolean) – If false then only the id and name of the models and entity types will be returned

  • with_property (string) – If specified with a property name, returns all models that the property use.

Status Codes

  • 200 OK – An array of models

Response JSON Object

  • [] (object) –

POST /models

EXPERIMENTAL: Adds one or more models to the list of models

Query Parameters

  • force (boolean) – When this is set to “true” it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.

Request JSON Object

  • [] (object) –

Status Codes

  • 200 OK – An array of models

Response JSON Object

  • [] (object) –

GET /models/{model_id}

EXPERIMENTAL: Returns the specified model

Parameters

  • model_id (string) – The id of the model

Query Parameters

  • effective (boolean) – If true then implict and explicit models will be merged in the response.

  • verbose (boolean) – If false then only the id and name of the model and entity types will be returned

Status Codes
DELETE /models/{model_id}

EXPERIMENTAL: Deletes the specified model

Parameters

  • model_id (string) – The id of the model

Status Codes
GET /models/{model_id}/{entity_type_id}

EXPERIMENTAL: Returns the specified entity type in a model

Parameters

  • model_id (string) – The id of the model

  • entity_type_id (string) – The id of the entity type

Query Parameters

  • effective (boolean) – If true then implict and explicit models will be merged in the response.

Status Codes
GET /pipes

Returns a list of all the pipes

Query Parameters

  • verbose (boolean) – When set to true the pipe information will be more verbose.

  • fields (array) – Specify which top-level keys in the pipe objects to return/omit.

Status Codes

  • 200 OK – An array of pipes

Response JSON Object

  • []._id (string) – (required)

  • [].cached_response_info.age (number) – The age (in seconds) of the cached information. This information can be derived from the “cache_time” property, but is included as a debug-aid. (required)

  • [].cached_response_info.timestamp (string) – The date and time the information was cached. (required)

  • [].config.effective._id (string) – (required)

  • [].config.effective.principals[] (string) –

  • [].config.effective.pump (object) – (required)

  • [].config.effective.sink.dataset (string) –

  • [].config.effective.sink.type (string) – (required)

  • [].config.effective.source.dataset (string) –

  • [].config.effective.source.type (string) – (required)

  • [].config.effective.type (string) – (required)

  • [].config.original._id (string) – (required)

  • [].config.original.metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

  • [].config.original.type (string) – (required)

  • [].runtime.config-errors[].elements (string) – The JSON path of the json element in the configuration that caused the error. (required)

  • [].runtime.config-errors[].level (string) – The severity-level of the error. (required)

  • [].runtime.config-errors[].msg (string) – A human-readable description of the error. (required)

  • [].runtime.dependencies[] (string) –

  • [].runtime.is-disabled (boolean) –

  • [].runtime.is-running (boolean) – (required)

  • [].runtime.is-valid-config (boolean) – (required)

  • [].runtime.queues (object) –

POST /pipes

Creates one or more pipes

Query Parameters

  • force (boolean) – When this is set to “true” it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.

Request JSON Object

  • []._id (string) – (required)

  • [].metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

  • [].type (string) – (required)

Status Codes

  • 200 OK – An array containing the new pipes

Response JSON Object

  • []._id (string) – (required)

  • [].cached_response_info.age (number) – The age (in seconds) of the cached information. This information can be derived from the “cache_time” property, but is included as a debug-aid. (required)

  • [].cached_response_info.timestamp (string) – The date and time the information was cached. (required)

  • [].config.effective._id (string) – (required)

  • [].config.effective.principals[] (string) –

  • [].config.effective.pump (object) – (required)

  • [].config.effective.sink.dataset (string) –

  • [].config.effective.sink.type (string) – (required)

  • [].config.effective.source.dataset (string) –

  • [].config.effective.source.type (string) – (required)

  • [].config.effective.type (string) – (required)

  • [].config.original._id (string) – (required)

  • [].config.original.metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

  • [].config.original.type (string) – (required)

  • [].runtime.config-errors[].elements (string) – The JSON path of the json element in the configuration that caused the error. (required)

  • [].runtime.config-errors[].level (string) – The severity-level of the error. (required)

  • [].runtime.config-errors[].msg (string) – A human-readable description of the error. (required)

  • [].runtime.dependencies[] (string) –

  • [].runtime.is-disabled (boolean) –

  • [].runtime.is-running (boolean) – (required)

  • [].runtime.is-valid-config (boolean) – (required)

  • [].runtime.queues (object) –

GET /pipes/{pipe_id}

Returns the specified pipe

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • fields (array) – Specify which top-level keys in the pipe object to return/omit.

Status Codes
Response JSON Object

  • _id (string) – (required)

  • cached_response_info.age (number) – The age (in seconds) of the cached information. This information can be derived from the “cache_time” property, but is included as a debug-aid. (required)

  • cached_response_info.timestamp (string) – The date and time the information was cached. (required)

  • config.effective._id (string) – (required)

  • config.effective.principals[] (string) –

  • config.effective.pump (object) – (required)

  • config.effective.sink.dataset (string) –

  • config.effective.sink.type (string) – (required)

  • config.effective.source.dataset (string) –

  • config.effective.source.type (string) – (required)

  • config.effective.type (string) – (required)

  • config.original._id (string) – (required)

  • config.original.metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

  • config.original.type (string) – (required)

  • runtime.config-errors[].elements (string) – The JSON path of the json element in the configuration that caused the error. (required)

  • runtime.config-errors[].level (string) – The severity-level of the error. (required)

  • runtime.config-errors[].msg (string) – A human-readable description of the error. (required)

  • runtime.dependencies[] (string) –

  • runtime.is-disabled (boolean) –

  • runtime.is-running (boolean) – (required)

  • runtime.is-valid-config (boolean) – (required)

  • runtime.queues (object) –

DELETE /pipes/{pipe_id}

Deletes the specified pipe

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
GET /pipes/{pipe_id}/config

Returns the configuration of the specified pipe

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes

  • 200 OK – The pipe configuration

Response JSON Object

  • _id (string) – (required)

  • metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

  • type (string) – (required)

PUT /pipes/{pipe_id}/config

Updates the configuration of the specified pipe

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • force (boolean) – When this is set to “true” it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.

Request JSON Object

  • _id (string) – (required)

  • metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

  • type (string) – (required)

Status Codes
Response JSON Object

  • _id (string) – (required)

  • cached_response_info.age (number) – The age (in seconds) of the cached information. This information can be derived from the “cache_time” property, but is included as a debug-aid. (required)

  • cached_response_info.timestamp (string) – The date and time the information was cached. (required)

  • config.effective._id (string) – (required)

  • config.effective.principals[] (string) –

  • config.effective.pump (object) – (required)

  • config.effective.sink.dataset (string) –

  • config.effective.sink.type (string) – (required)

  • config.effective.source.dataset (string) –

  • config.effective.source.type (string) – (required)

  • config.effective.type (string) – (required)

  • config.original._id (string) – (required)

  • config.original.metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

  • config.original.type (string) – (required)

  • runtime.config-errors[].elements (string) – The JSON path of the json element in the configuration that caused the error. (required)

  • runtime.config-errors[].level (string) – The severity-level of the error. (required)

  • runtime.config-errors[].msg (string) – A human-readable description of the error. (required)

  • runtime.dependencies[] (string) –

  • runtime.is-disabled (boolean) –

  • runtime.is-running (boolean) – (required)

  • runtime.is-valid-config (boolean) – (required)

  • runtime.queues (object) –

GET /pipes/{pipe_id}/entities

Returns the entities produced by the specified pipe

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

  • since (string) – Specifies the minimum since-value.

  • stage (string) – Can be set to ‘source’, ‘before-transforms’, ‘after-transforms’ or ‘sink’ (default). ‘source’ returns entities as they come out of the source. ‘before-transforms’ returns entities as they are fed into the first transform. ‘after-transforms’ return entities as they look after the last transform. ‘sink’ returns entities as they look as they enter the sink.

Status Codes
Response JSON Object

  • []._id (string) – (required)

GET /pipes/{pipe_id}/log

Returns the entities in the execution log dataset

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

  • since (integer) – An opaque value that can be used to efficiently skip already seen entities.

  • history (boolean) – If this is true (the default) all entities, including replaced ones, will be returned. If this is false, only the latest version of the entities will be returned

  • reverse (boolean) – If this is false (the default) the entities will be returned from the start of the dataset log. If this is true, the entities will be returned from the end of the dataset log instead

  • deleted (boolean) – If this is true (the default) the entities marked as deleted will also be returned from the dataset log. If this is false, the entities that are marked as deleted will not included in result. If you request the complete history the deletes will always be included.

Status Codes
Response JSON Object

  • []._id (string) – (required)

  • []._updated (integer) – The dataset offset of this entity. (required)

OPTIONS /pipes/{pipe_id}/log

Returns the OPTIONS with this endpoint

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • since (integer) – An opaque value that can be used to efficiently skip already seen entities.

  • history (boolean) – If this is true (the default) all entities, including replaced ones, will be returned. If this is false, only the latest version of the entities will be returned

  • reverse (boolean) – If this is false (the default) the entities will be returned from the start of the dataset log. If this is true, the entities will be returned from the end of the dataset log instead

  • deleted (boolean) – If this is true (the default) the entities marked as deleted will also be returned from the dataset log. If this is false, the entities that are marked as deleted will not included in result. If you request the complete history the deletes will always be included.

  • webhook (string) – EXPERIMENTAL: If specified, the webhook URL will be POST-ed to whenever there is new data available in the dataset after the request has been processed.

  • token (string) – EXPERIMENTAL: The token associated with the webhook. It’s required if ‘webhook’ is set, if not then a Badrequest is thrown.

Status Codes
GET /pipes/{pipe_id}/generate-schema-definition

Returns info about the schema of the entities processed by the pipe

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • sample_size (integer) – Specifies the number of entities to sample from the source

  • keys_only (boolean) – Specifies if only the array of keys should returned, or the whole schema

Status Codes
GET /pipes/{pipe_id}/pump

Returns info about the pump of the specified pipe

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
POST /pipes/{pipe_id}/pump

Runs some operation on the pump. The operation is specified by the ‘operation’ form parameter in the request.

The following operations exists:

“start”:

Starts a new run of the pump. A pump is typically run automatically at scheduled intervals, but with this operation a pump can be started manually.

“start-rescan”:

Starts a new rescan, unless a rescan is already running.

“stop”:

Stops the pump, if it is running (both rescans and normal pump runs are stopped). If the pump is not running, this operation has no effect.

“enable”:

Enables the pump. This means that the pump can be run automatically by the system (usually on some fixed schedule).

“disable”:

Disables the pump. This means that the pump cannot be run automatically by the system. Note that it is still possible to start the pump manually with the “start”-operation.

“update-last-seen”:

Updates the “last-seen” value of the pump. This is the value the pump uses to figure out at which point in the source-data it stopped at its last run. The format of the “last-seen” form parameter depends on the source-system. It could be a date, and it could be some opaque binary value.

To clear the “last-seen” value of the pump, set the “last-seen” form parameter to an empty string. This will make the pump behave as if it was running for the first time. This is useful in cases where one wants to reprocess the data from scratch for some reason.

“set-last-seen-to-end”:

Updates the “last-seen” value of the pump such that the pump thinks that it has seen all the source-data. Not all source-types supports this operation. NOTE: Doing this may result in data-loss, since any unread entities in the source will not be read. But it is sometimes useful during development and testing; for instance when one has a huge existing source-dataset, but only want to run the pipe against new entities.

“reset-tracking” (EXPERIMENTAL):

Resets the dependency tracking so that it will continue starting from the end of dependent datasets. NOTE: It is not safe to use this operation while the pipe is running.

Note that tracking will continue from what is the end of the datasets at the point in time when the pump runs, not the time at which this call is made.

Note that dependency tracking will then be skipped for untracked offsets, causing the output to be potentially incorrect. Use this feature only during development, or when you intend to do a full sync soon after the reset.

“reset-rescan”:

Make the next rescan runs start from the beginning of the source-dataset, even if the last rescan was interrupted before it finished. (Normally, if the last rescan run was interrupted, the next rescan run will resume from where the interrupted rescan run got to).

“discard-retries”:

Writes a ‘pump-discard-retries’ entity to the pipe execution log. This will make the pump ignore any pending retries due to write-errors on the next run, in effect discarding any retries of these previously failed entities. Note that such discarded retryable entities are not written to the dead-letter dataset.

“discard-inferred-schema”:

Deletes any accumulated inferred schema information for the pipe. Note: you would normally reset the pipe after doing this. This operation is useful for pipes that doesn’t support continuation as these pipes don’t automatically delete the inferred schema on reset.

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
POST /pipes/{pipe_id}/webhook

Schedules the pump of the pipe to run. The json body must include a “token” property that must match the token generated by the pipe when it registered the webhook. If not, it will throw a 404 error which will in turn unregister the webhook on the sender side.

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
GET /pipes/{pipe_id}/entity-types/source

Returns the pipe’s source entity type

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
GET /pipes/{pipe_id}/entity-types/sink

Returns the pipe’s sink entity type

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
GET /datasets

Returns a list of all the datasets

Query Parameters

  • verbose (boolean) – When set to true the dataset information will be more verbose.

Status Codes

  • 200 OK – An array of datasets

Response JSON Object

  • []._id (string) – (required)

  • [].cached_response_info.age (number) – The age (in seconds) of the cached information. This information can be derived from the “cache_time” property, but is included as a debug-aid. (required)

  • [].cached_response_info.timestamp (string) – The date and time the information was cached. (required)

GET /datasets/{dataset_id}

Returns the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

Status Codes
Response JSON Object

  • _id (string) – (required)

  • cached_response_info.age (number) – The age (in seconds) of the cached information. This information can be derived from the “cache_time” property, but is included as a debug-aid. (required)

  • cached_response_info.timestamp (string) – The date and time the information was cached. (required)

DELETE /datasets/{dataset_id}

Deletes the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

Status Codes
POST /datasets/{dataset_id}

Performs some operation on the specified dataset. The operation to do is specified with the “operation” form parameter. Supported operations are “rollback-circuit-breaker” and “commit-circuit-breaker”.

Parameters

  • dataset_id (string) – The id of the dataset

Status Codes
GET /datasets/{dataset_id}/entities

Returns the entities in the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

Query Parameters

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

  • since (integer) – An opaque value that can be used to efficiently skip already seen entities.

  • history (boolean) – If this is true (the default) all entities, including replaced ones, will be returned. If this is false, only the latest version of the entities will be returned

  • reverse (boolean) – If this is false (the default) the entities will be returned from the start of the dataset log. If this is true, the entities will be returned from the end of the dataset log instead

  • deleted (boolean) – If this is true (the default) the entities marked as deleted will also be returned from the dataset log. If this is false, the entities that are marked as deleted will not included in result. If you request the complete history the deletes will always be included.

  • populated (boolean) – If this is true the response will be 404 if the dataset has not yet been populated. It is not enough for the dataset to have data, but the data that’s there must reflect a complete view of the dataset’s source. In other words; the dataset must be fully populated. In practice this means that the pipe that populates the dataset has not yet had a complete full run. Normally 404 is only returned when the dataset does not exist.

  • uncommitted (boolean) – If true then the response may include uncommitted entities. This is only relevant if the pipe that writes to the dataset have a circuit breaker enabled. Use this for debugging purposes only.

  • subset (string) – If specified then the specified JSON encoded subset expression will be used to retrieve entities from a dataset subset. If the subset does not exist, then 404 is returned.

Status Codes
Response JSON Object

  • []._id (string) – (required)

  • []._updated (integer) – The dataset offset of this entity. (required)

OPTIONS /datasets/{dataset_id}/entities

Returns the OPTIONS with this endpoint

Parameters

  • dataset_id (string) – The id of the dataset

Query Parameters

  • since (integer) – An opaque value that can be used to efficiently skip already seen entities.

  • history (boolean) – If this is true (the default) all entities, including replaced ones, will be returned. If this is false, only the latest version of the entities will be returned

  • reverse (boolean) – If this is false (the default) the entities will be returned from the start of the dataset log. If this is true, the entities will be returned from the end of the dataset log instead

  • deleted (boolean) – If this is true (the default) the entities marked as deleted will also be returned from the dataset log. If this is false, the entities that are marked as deleted will not included in result. If you request the complete history the deletes will always be included.

  • subset (string) – If specified then the specified JSON encoded subset expression will be used to retrieve entities from a dataset subset. If the subset does not exist, then 404 is returned.

  • webhook (string) – EXPERIMENTAL: If specified, the webhook URL will be POST-ed to whenever there is new data available in the dataset after the request has been processed.

  • token (string) – EXPERIMENTAL: The token associated with the webhook. It’s required if ‘webhook’ is set, if not then a Badrequest is thrown.

Status Codes
POST /datasets/{dataset_id}/entities

Puts the specified entities into the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

Query Parameters

  • force (boolean) – If ‘false’, then the hashes of the posted entity and the previous version will be compared before storing the entity. The entity will not be written to the dataset if the hashes are the same. If ‘true’, then the entity will always be written to the dataset. The default is ‘false’.

Status Codes
GET /datasets/{dataset_id}/entities/{rest_of_path}

Deprecated. Use the /entity endpoint. Returns the specified entity in the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

  • rest_of_path (string) – The id of the entity

Query Parameters

  • subset (string) – If specified then the specified JSON encoded subset expression will be used to retrieve the entity from a dataset subset. If the subset does not exist, then 404 is returned.

Status Codes
Response JSON Object

  • _id (string) – (required)

  • _updated (integer) – The dataset offset of this entity. (required)

GET /datasets/{dataset_id}/entity

Returns the specified entity in the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

Query Parameters

  • entity_id (string) – The id of the entity

  • subset (string) – If specified then the specified JSON encoded subset expression will be used to retrieve the entity from a dataset subset. If the subset does not exist, then 404 is returned.

  • offset (integer) – Look up the entity id at this specific offset in the dataset. If it is not there, or there is another entity at that offset, then 404 is returned.

  • uncommitted (boolean) – If true then the response may include uncommitted entities. This is only relevant if the pipe that writes to the dataset have a circuit breaker enabled.

Status Codes
Response JSON Object

  • _id (string) – (required)

  • _updated (integer) – The dataset offset of this entity. (required)

GET /datasets/{dataset_id}/sdshare-collection

Returns a sdshare collection feed for the entities in the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

Status Codes
GET /datasets/{dataset_id}/sdshare-fragments

Returns a sdshare fragments feed for the entities in the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

Status Codes
GET /datasets/{dataset_id}/sdshare-fragments/{rest_of_path}

Returns a sdshare fragment for the specified entity in the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

  • rest_of_path (string) – The id of the entity-id

Status Codes
GET /datasets/{dataset_id}/indexes

Returns the indexes on the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

Status Codes

  • 200 OK – The indexes of the dataset.

Response JSON Object

  • [] (object) –

DELETE /datasets/{dataset_id}/indexes/{index_int_id}

Deletes the specified dataset

Parameters

  • dataset_id (string) – The id of the dataset

  • index_int_id (integer) – The index integer id

Status Codes
GET /datasets/{dataset_id}/generate-schema-definition

Returns info about the schema of the entities in the dataset

Parameters

  • dataset_id (string) – The id of the dataset

Query Parameters

  • sample_size (integer) – Specifies the number of entities to sample from the dataset

  • keys_only (boolean) – Specifies if only the array of keys should returned, or the whole schema

Status Codes
GET /config

Returns the all configuration of the node in the default (i.e empty) config-group. The config is returned as an array of json objects, or as a zip-archive, depending on the value of the ‘Accepts’ header.

Status Codes

  • 200 OK – The configuration

Response JSON Object

  • []._id (string) – (required)

  • [].type (string) – (required)

PUT /config

Overwrites all configuration of the node in the default (i.e empty) config-group.

Query Parameters

  • force (boolean) – When this is set to “true” it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.

Status Codes
GET /config/{config-group}

Returns all configuration that has been tagged by by the specified config-group.

Parameters

  • config-group (string) – The id of the config-group to get the config from.

Query Parameters

  • force (boolean) – When this is set to “true” it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.

Status Codes

  • 200 OK – The configuration

Response JSON Object

  • []._id (string) – (required)

  • [].type (string) – (required)

PUT /config/{config-group}

Overwrites all configuration that has been tagged by the specified config-group’.

Parameters

  • config-group (string) – The id of the config-group to post the config to.

Status Codes
GET /config-history/entity

Returns all configuration history for a specific config entity

Query Parameters

  • entity_id (string) – The id of the entity

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

  • since (integer) – An opaque value that can be used to efficiently skip already seen entities.

  • reverse (boolean) – If this is false (the default) the entities will be returned from the start of the dataset log. If this is true, the entities will be returned from the end of the dataset log instead

Status Codes

  • 200 OK – The configuration history for the config entity

Response JSON Object

  • []._id (string) – (required)

  • [].type (string) – (required)

GET /
Query Parameters

  • aggregated (boolean) – If set to false then the response will not be aggregated.

Status Codes
Response JSON Object

  • status.git-revision (string) – This is an internal value that refers to the git revision that was used to build this version of the sesam portal.

  • status.teamcity-buildnumber (string) – This is an internal value that refers to the build-job that produced this version of the sesam portal.

POST /
Status Codes
GET /env

Returns the currently defined environment variable values.

Status Codes
POST /env

Adds a variable or list of variables to the environment variable manager. If a variable already exists, it is overwritten.

Status Codes
PUT /env

Adds a variable or list of variables to the environment variable manager. If a variable already exists, it is overwritten.

Status Codes
PATCH /env

Adds a variable or list of variables to the environment variable manager. If a variable already exists, it is overwritten.

Status Codes
DELETE /env/{env_var}

Deleted the specified environment variable.

Parameters

  • env_var (string) – The name of the environment variable to delete

Status Codes
GET /secrets

Returns a list of the names of the defined secrets.

Status Codes
PUT /secrets

Adds the secrets specified in the payload. The payload must be a JSON object where the keys are the secret names and the values are the secret values. If a secret already exists, it is overwritten.

Status Codes
POST /secrets

Adds the secrets specified in the payload. The payload must be a JSON object where the keys are the secret names and the values are the secret values. If a secret already exists, it is overwritten. Existing secrets are not deleted.

Status Codes
DELETE /secrets/{secret_key}

Deleted the specified secret.

Parameters

  • secret_key (string) – The name of the secret to delete

Status Codes
GET /health

Sesam api health information

Status Codes
GET /ping

Sesam api probe API

Status Codes
GET /license

Returns info about the current license

Status Codes
PUT /license

Upload a new license key. The new license will replace the old license if valid.

Status Codes
GET /namespaces

Returns the service’s namespaces (includes default namespaces)

Status Codes
GET /metadata

Returns the service metadata

Status Codes
Response JSON Object

  • [] (object) –

PUT /metadata

Updates the service metadata

Status Codes
Response JSON Object

  • [] (object) –

DELETE /metadata

Deletes all service metadata

Status Codes
Response JSON Object

  • [] (object) –

GET /publishers/{pipe_id}/sdshare-collection

publisher endpoint sdshare collection feed

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
GET /publishers/{pipe_id}/sdshare-fragments

publisher endpoint sdshare fragments feed

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • since (string) – Specifies the minimum since-value.

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

Status Codes
GET /publishers/{pipe_id}/entities

publisher endpoint json entities

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • since (string) – Specifies the minimum since-value.

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

Status Codes
GET /publishers/{pipe_id}/entities/{filename}

publisher endpoint json entities - filename in url version

Parameters

  • pipe_id (string) – The id of the pipe

  • filename (string) – The filename to use as attachment filename

Query Parameters

  • since (string) – Specifies the minimum since-value.

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

Status Codes
GET /publishers/{pipe_id}/csv

publisher csv endpoint

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • since (string) – Specifies the minimum since-value.

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

  • linked_excel_file (string) – Instead of returning a CSV file, return a Excel file with a “connection” link to the original CSV URL. This parameter contains the filename to use.

Status Codes
OPTIONS /publishers/{pipe_id}/csv/

publisher csv endpoint OPTIONS (for office)

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
GET /publishers/{pipe_id}/csv/{filename}

publisher csv endpoint - filename in url version

Parameters

  • pipe_id (string) – The id of the pipe

  • filename (string) – The filename to use as attachment filename

Query Parameters

  • since (string) – Specifies the minimum since-value.

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

  • linked_excel_file (string) – Instead of returning a CSV file, return a Excel file with a “connection” link to the original CSV URL. This parameter contains the filename to use.

Status Codes
GET /publishers/{pipe_id}/excel

publisher excel endpoint

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • since (string) – Specifies the minimum since-value.

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

Status Codes
OPTIONS /publishers/{pipe_id}/excel/

publisher excel endpoint OPTIONS (for office)

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
GET /publishers/{pipe_id}/excel/{filename}

publisher excel endpoint - filename in url version

Parameters

  • pipe_id (string) – The id of the pipe

  • filename (string) – The filename to use as attachment filename

Query Parameters

  • since (string) – Specifies the minimum since-value.

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

Status Codes
GET /publishers/{pipe_id}/xml

publisher xml endpoint

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • since (string) – Specifies the minimum since-value.

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

Status Codes
GET /publishers/{pipe_id}/xml/{filename}

publisher xml endpoint - filename in url version

Parameters

  • pipe_id (string) – The id of the pipe

  • filename (string) – The filename to use as attachment filename

Query Parameters

  • since (string) – Specifies the minimum since-value.

  • limit (integer) – Specifies the maximum number of entities to return. If this is not specified, all available entities are returned..

Status Codes
OPTIONS /publishers/{pipe_id}/xml/

publisher xml endpoint OPTIONS (for office)

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
GET /publishers/{pipe_id}/shareable-links

Returns the shareable links that have been created for this publisher

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
Response JSON Object

  • [] (any) – A shareable link to a publisher endpoint.

POST /publishers/{pipe_id}/shareable-links

Create a new shareable link for this publisher

Parameters

  • pipe_id (string) – The id of the pipe

Status Codes
DELETE /publishers/{pipe_id}/shareable-links/{shareable_link_id}

Deletes the specified shareable link

Parameters

  • pipe_id (string) – The id of the pipe

  • shareable_link_id (string) – The id of the shareable link

Status Codes
POST /receivers/{pipe_id}/sdshare-push-receiver

Sesam api receiver endpoint - uses the SDShare Push protocol. Pushes n-triples to the named pipe. This is only supported for pipes that have an ‘http_endpoint’ source.

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • resource (string) – Specifies the root resources

Status Codes
POST /receivers/{pipe_id}/entities

Sesam api receiver endpoint - uses the JSON Push protocol. Pushes JSON entities to the named pipe. This is only supported for pipes that have an ‘http_endpoint’ source.

Parameters

  • pipe_id (string) – The id of the pipe

Query Parameters

  • sequence_id (string) – A string token that is generated every time the data sync is started. Included in all requests.

  • is_full (boolean) – A boolean. Has the value true if this is a full data sync, and false if not. Included in all requests. The default value is false.

  • request_id (string) – A string token that is generated for every request. Included in all requests.

  • previous_request_id (string) – A string token referencing the request_id of the previous request. Included in all but the first request.

  • is_first (boolean) – A boolean. Included in the first request with the value true.

  • is_last (boolean) – A boolean. Included in the last request with the value true.

Status Codes
Response JSON Object

  • common_ancestor_entity (any) –

  • existing_entity (any) –

  • input_entity (any) –

  • updated_entity (any) –

GET /systems

Returns a list of all the systems

Query Parameters

  • verbose (boolean) – If true then the ‘storage’ property will contain a breakdown of the disk-usage

Status Codes

  • 200 OK – An array of systems

Response JSON Object

  • []._id (string) – (required)

  • [].cached_response_info.age (number) – The age (in seconds) of the cached information. This information can be derived from the “cache_time” property, but is included as a debug-aid. (required)

  • [].cached_response_info.timestamp (string) – The date and time the information was cached. (required)

POST /systems

Creates one or more systems

Query Parameters

  • force (boolean) – When this is set to “true” it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.

Request JSON Object

  • []._id (string) – (required)

  • [].metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

Status Codes

  • 200 OK – An array containing the new systems

Response JSON Object

  • []._id (string) – (required)

  • [].cached_response_info.age (number) – The age (in seconds) of the cached information. This information can be derived from the “cache_time” property, but is included as a debug-aid. (required)

  • [].cached_response_info.timestamp (string) – The date and time the information was cached. (required)

GET /systems/{system_id}

Returns the specified system

Parameters

  • system_id (string) – The id of the system

Status Codes
Response JSON Object

  • _id (string) – (required)

  • cached_response_info.age (number) – The age (in seconds) of the cached information. This information can be derived from the “cache_time” property, but is included as a debug-aid. (required)

  • cached_response_info.timestamp (string) – The date and time the information was cached. (required)

DELETE /systems/{system_id}

Deletes the specified system

Parameters

  • system_id (string) – The id of the system

Status Codes
GET /systems/{system_id}/logs

Returns the logs from the microservice. By default it returns the last 1000 lines.

Parameters

  • system_id (string) – The id of the system

Query Parameters

  • since (string) – Specifies from which point in time to stream the logs. The value must be an ISO datetime value, e.g. ‘2016-11-08T08:28:45.880594510Z’. Note that all log lines after this point in the log will be returned.

Status Codes

  • 200 OK – The microservice logs data

GET /systems/{system_id}/status

Returns the status from the system (if microservice, then a subset of docker inspect)

Parameters

  • system_id (string) – The id of the system

Status Codes

  • 200 OK – The microservice status data

POST /systems/{system_id}/reload

Queues a operation to pull a new docker image and recreate the microservice (i.e. asynchronously)

Parameters

  • system_id (string) – The id of the system

Status Codes
GET /systems/{system_id}/proxy/{rest_of_path}

Passes the request through to the microservice and returns the response

Parameters

  • system_id (string) – The id of the system

  • rest_of_path (string) – The relative path to access on the microservice

Status Codes

  • 200 OK – The proxied response from the microservice

POST /systems/{system_id}/proxy/{rest_of_path}

Passes the request through to the microservice and returns the response

Parameters

  • system_id (string) – The id of the system

  • rest_of_path (string) – The relative path to access on the microservice

Status Codes

  • 200 OK – The proxied response from the microservice

PUT /systems/{system_id}/proxy/{rest_of_path}

Passes the request through to the microservice and returns the response

Parameters

  • system_id (string) – The id of the system

  • rest_of_path (string) – The relative path to access on the microservice

Status Codes

  • 200 OK – The proxied response from the microservice

PATCH /systems/{system_id}/proxy/{rest_of_path}

Passes the request through to the microservice and returns the response

Parameters

  • system_id (string) – The id of the system

  • rest_of_path (string) – The relative path to access on the microservice

Status Codes

  • 200 OK – The proxied response from the microservice

DELETE /systems/{system_id}/proxy/{rest_of_path}

Passes the request through to the microservice and returns the response

Parameters

  • system_id (string) – The id of the system

  • rest_of_path (string) – The relative path to access on the microservice

Status Codes

  • 200 OK – The proxied response from the microservice

GET /systems/{system_id}/config

Returns the configuration of the specified system

Parameters

  • system_id (string) – The id of the system

Status Codes

  • 200 OK – The system configuration

Response JSON Object

  • _id (string) – (required)

  • metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

PUT /systems/{system_id}/config

This service lets the user update a system’s configuration by sending a PUT-request with the new configuration. The id of the system is specified by the ‘{system_id}’ part of the url.

Parameters

  • system_id (string) – The id of the system

Query Parameters

  • force (boolean) – When this is set to “true” it forces the server to accept configuration errors and do a best-effort attempt to apply the new configuration. This is rarely a good idea.

Request JSON Object

  • _id (string) – (required)

  • metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

Status Codes

  • 200 OK – The system configuration

Response JSON Object

  • _id (string) – (required)

  • metadata.$config-group (string) – This can be set to specify that this pipe belongs to the specified config-group. If this value is not set, the pipe belongs to the default config-group. See also the ‘/config/{config-group}’ endpoint.

GET /systems/{system_id}/secrets

Returns a list of the names of the defined secrets for the specified system.

Parameters

  • system_id (string) – The id of the system

Status Codes
Response JSON Object

  • [] (string) –

PUT /systems/{system_id}/secrets

Overwrites the secrets for the specified system. The payload must be a JSON object where the keys are the secret names and the values are the secret values.

Parameters

  • system_id (string) – The id of the system

Status Codes
POST /systems/{system_id}/secrets

Adds the secrets specified in the payload to the specified system. The payload must be a JSON object where the keys are the secret names and the values are the secret values. If a secret already exists, it is overwritten. Existing secrets are not deleted.

Parameters

  • system_id (string) – The id of the system

Status Codes
DELETE /systems/{system_id}/secrets/{secret_key}

Deletes the specified secret from the specified system

Parameters

  • system_id (string) – The id of the system

  • secret_key (string) – The name of the secret to delete

Status Codes

Portal API Reference

GET /api

Returns information about the sesam portal.

Status Codes
Response JSON Object

  • authentication_providers[].id (string) – The unique id of the provider (required)

  • authentication_providers[].login_button_icon (string) – Optional. An url to the icon that should be used on the login-button for this provider.

  • authentication_providers[].login_button_text (string) – Optional. The text to display on the login button.

  • authentication_providers[].login_button_tooltip (string) – Optional. The mouse-over tooltip to display on the login button.

  • authentication_providers[].login_url (string) – The url to go to to start authenticating with this provider (required)

  • status.build-date (string) –

  • status.feature-level (integer) – A positive integer that indicates which api features this version of the sesam-portal supports. (required)

  • status.git-revision (string) – This is an internal value that refers to the git revision that was used to build this version of the sesam portal.

  • status.health_status.message (string) – If the status is not “ok”, this property contains a human-readable message describing the problem.

  • status.health_status.status (string) – (required)

  • status.is_email_verification_required (boolean) –

  • status.is_fallback_mode (boolean) –

  • status.is_internal_users_enabled (boolean) –

  • status.is_itest_mode (boolean) –

  • status.revision (string) –

  • status.start_time (string) –

  • status.teamcity-buildnumber (string) – This is an internal value that refers to the build-job that produced this version of the sesam portal.

  • status.tos_version (number) –

  • status.uptime (string) –

  • status.version (string) –

  • tos_version (number) – The current version of the Terms of Service

GET /api/profile

Returns information about the currently logged-in user.

Status Codes
Response JSON Object

  • supported-operations.activate_portal_admin_powers (any) – (required)

  • supported-operations.create_paymentmethod (any) – (required)

  • supported-operations.create_subscription (any) – (required)

  • supported-operations.create_trial_subscription (any) – (required)

  • supported-operations.delete_account (any) – (required)

  • supported-operations.request_email_verification (any) – (required)

  • supported-operations.request_trial_subscription (any) – (required)

  • supported-operations.send_reset_password_email (any) – (required)

  • supported-operations.update_user_profile (any) – (required)

  • userInfo.isLoggedIn (boolean) –

  • userInfo.lastRequestTrial.created_time (string) – The time when the user made the request, as a ISO 8601 formatted string.

  • userInfo.lastRequestTrial.dismissed_from_gui (boolean) – This can be set to true to hide a denied request from the user’s gui.

  • userInfo.lastRequestTrial.responded_time (string) – The time when the request was answered, as a ISO 8601 formatted string.

  • userInfo.lastRequestTrial.response (string) – A text describing the reason behind the result (typically used to explain why the request was denied.

  • userInfo.lastRequestTrial.status (string) – The result of the request.

  • userInfo.lastRequestTrial.user_submitted_information (object) – The information the user submits when requesting information. This information is diplayed to the sesam employee that reviews the “create trial” request. The exact properties that are present is decided by the GUI; both the backend storage and the admin form the sesam employee uses can handle any number and types of properties.

  • userInfo.profile.email (string) –

  • userInfo.profile.email_is_verified (boolean) –

  • userInfo.profile.name (string) –

  • userInfo.profile.nickname (string) –

  • userInfo.profile.picture (string) –

  • userInfo.providerIds[] (string) –

  • userInfo.providerWhitelist[] (string) –

  • userInfo.user_id (string) –

PUT /api/profile

Updates information about the currently logged-in user. This endpoint accepts the same json structure as the GET /api/profile endpoint produces, but only a few of the fields in that structure will be used, since the user is only allowed to change a few of the fields. The “name” field can be changed, but the “email” field can not be changed, for instance. This endpoint also accept a “sparse” json-structure, that only contains the field(s) that the client wants to modify. The values represented by any “missing” fields will not be modified; if for instance the json only contains the “picture”-field, the “name”-field will not be modified.

Request JSON Object

  • userInfo.approvedTos (number) –

  • userInfo.isPortalAdmin (boolean) – This property can only be modified by the special portal-admin users. The portal-admin powers of such users are disabled by default, and must be explicitly activated by setting this property to ‘true’.

  • userInfo.profile.name (string) –

  • userInfo.profile.nickname (string) –

  • userInfo.profile.picture (string) –

  • userInfo.providerIds[] (string) –

  • userInfo.providerWhitelist[] (string) –

Status Codes
Response JSON Object

  • supported-operations.activate_portal_admin_powers (any) – (required)

  • supported-operations.create_paymentmethod (any) – (required)

  • supported-operations.create_subscription (any) – (required)

  • supported-operations.create_trial_subscription (any) – (required)

  • supported-operations.delete_account (any) – (required)

  • supported-operations.request_email_verification (any) – (required)

  • supported-operations.request_trial_subscription (any) – (required)

  • supported-operations.send_reset_password_email (any) – (required)

  • supported-operations.update_user_profile (any) – (required)

  • userInfo.isLoggedIn (boolean) –

  • userInfo.lastRequestTrial.created_time (string) – The time when the user made the request, as a ISO 8601 formatted string.

  • userInfo.lastRequestTrial.dismissed_from_gui (boolean) – This can be set to true to hide a denied request from the user’s gui.

  • userInfo.lastRequestTrial.responded_time (string) – The time when the request was answered, as a ISO 8601 formatted string.

  • userInfo.lastRequestTrial.response (string) – A text describing the reason behind the result (typically used to explain why the request was denied.

  • userInfo.lastRequestTrial.status (string) – The result of the request.

  • userInfo.lastRequestTrial.user_submitted_information (object) – The information the user submits when requesting information. This information is diplayed to the sesam employee that reviews the “create trial” request. The exact properties that are present is decided by the GUI; both the backend storage and the admin form the sesam employee uses can handle any number and types of properties.

  • userInfo.profile.email (string) –

  • userInfo.profile.email_is_verified (boolean) –

  • userInfo.profile.name (string) –

  • userInfo.profile.nickname (string) –

  • userInfo.profile.picture (string) –

  • userInfo.providerIds[] (string) –

  • userInfo.providerWhitelist[] (string) –

  • userInfo.user_id (string) –

GET /api/profile2

Returns information about the currently logged-in user. If the user is not logged in a 401 response is returned instead. TODO replace the “/api/profile” endpoint with this when we deploy the unified frontend.

Status Codes

  • 200 OK – This returns the same response as the /api/profile endpoint

  • 401 Unauthorized – The user is not logged in

Response JSON Object

  • supported-operations.activate_portal_admin_powers (any) – (required)

  • supported-operations.create_paymentmethod (any) – (required)

  • supported-operations.create_subscription (any) – (required)

  • supported-operations.create_trial_subscription (any) – (required)

  • supported-operations.delete_account (any) – (required)

  • supported-operations.request_email_verification (any) – (required)

  • supported-operations.request_trial_subscription (any) – (required)

  • supported-operations.send_reset_password_email (any) – (required)

  • supported-operations.update_user_profile (any) – (required)

  • userInfo.isLoggedIn (boolean) –

  • userInfo.lastRequestTrial.created_time (string) – The time when the user made the request, as a ISO 8601 formatted string.

  • userInfo.lastRequestTrial.dismissed_from_gui (boolean) – This can be set to true to hide a denied request from the user’s gui.

  • userInfo.lastRequestTrial.responded_time (string) – The time when the request was answered, as a ISO 8601 formatted string.

  • userInfo.lastRequestTrial.response (string) – A text describing the reason behind the result (typically used to explain why the request was denied.

  • userInfo.lastRequestTrial.status (string) – The result of the request.

  • userInfo.lastRequestTrial.user_submitted_information (object) – The information the user submits when requesting information. This information is diplayed to the sesam employee that reviews the “create trial” request. The exact properties that are present is decided by the GUI; both the backend storage and the admin form the sesam employee uses can handle any number and types of properties.

  • userInfo.profile.email (string) –

  • userInfo.profile.email_is_verified (boolean) –

  • userInfo.profile.name (string) –

  • userInfo.profile.nickname (string) –

  • userInfo.profile.picture (string) –

  • userInfo.providerIds[] (string) –

  • userInfo.providerWhitelist[] (string) –

  • userInfo.user_id (string) –

DELETE /api/profile/{user_id}

Deletes the specified user.

Parameters

  • user_id (string) – The id of the user to delete.

Status Codes
GET /api/jwt

Returns the JSON Web Token for the currently logged in user.

Status Codes
POST /api/jwt

Returns the JSON Web Token for the user described in the post parameters (email+password).

Status Codes
GET /api/subscriptions/{subscription_id}/jwt

Returns the JSON Web Token for the specified subscription for the currently logged in user.

Parameters

  • subscription_id (string) – The subscription id

Status Codes
GET /api/jwt/publickey

Returns the RSA public key that can be used to verify the JWT signature

Status Codes
GET /api/jwt/zendesk

Returns the JWT to be used with the Zendesk authentication api for the currently logged in user

Status Codes
GET /api/jwt/zendesk-chat

Returns the JWT to be used with the Zendesk Chat authentication api for the currently logged in user

Status Codes
GET /api/subscriptions

Returns the subscriptions that this user is connected to.

Status Codes
Response JSON Object

  • []._updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • [].audit.created_by.email (string) –

  • [].audit.created_by.name (string) –

  • [].audit.created_by.picture (string) –

  • [].audit.created_by.user_id (string) –

  • [].audit.created_ts (string) –

  • [].audit.last_modified_by.email (string) –

  • [].audit.last_modified_by.name (string) –

  • [].audit.last_modified_by.picture (string) –

  • [].audit.last_modified_by.user_id (string) –

  • [].audit.last_modified_ts (string) –

  • [].connections[].id (string) – The name “id” is a special case; it represents the default sesam-node connection. When the item’s type is “databrowser”, the id refers to a databrowser in the “databrowser”-list in the “products”-part of the subscription info. (required)

  • [].connections[].name (string) – The human-redable name of the connection. (required)

  • [].connections[].type (string) – This specified the type of component this connection points to. (required)

  • [].connections[].url (string) – (required)

  • [].created (string) – (required)

  • [].current-users-member (any) –

  • [].description (string) – A short description of the subscription.

  • [].id (string) – (required)

  • [].is_unused_precreated_subscription (boolean) – Specified if this is an unused precreated subscription. Such subscriptions are kept in reserve and assigned to people when they try to create a new subscription. This saves people from having to wait for a new box to be provisioned.

  • [].licenses[].is-active-license (boolean) – This is set to true if this is the currently active license. A subscription might have several licenses; each license has an expiration date, and each time the customer will renews the license, a new entry is added to the subscription’s ‘licenses’ list.

  • [].licenses[].original._id (string) – (required)

  • [].licenses[].original.created (string) – (required)

  • [].licenses[].original.email (string) – (required)

  • [].licenses[].original.expires (string) – (required)

  • [].licenses[].signed (string) – The signed license key. This is only present for ‘on-premise’ subscriptions. For ‘in-cloud’ subscriptions the license-key is handled by the provisioner service and should never be shown to the customer.

  • [].name (string) – (required)

  • [].network.network-acl[].access (string) – (required)

  • [].network.network-acl[].address (string) – (required)

  • [].network.public-access (boolean) –

  • [].paymentmethod_id (string) – The id of the PaymentMethod that the licence-fee for this subscription should be billed to. This property is only present for subscriptions of the type “paid”.

  • [].paymentmethod_info.description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use. (required)

  • [].paymentmethod_info.id (string) – The internal id of this paymentmethod. (required)

  • [].paymentmethod_info.is_verified (boolean) – This is set to true when a Portal administrator (i.e a SESAM employee) has manually examined the payment information and checked that it is legitimate. Only portal administrators are allowed to change the value of this property. (required)

  • [].paymentmethod_info.name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use. (required)

  • [].paymentmethod_info.owner.email (string) – The email of the owner (required)

  • [].paymentmethod_info.owner.name (string) – The name of the owner (required)

  • [].paymentmethod_info.owner.picture (string) –

  • [].paymentmethod_info.owner.user_id (string) – The id of the owner (required)

  • [].paymentmethod_info.type (string) – The type of this paymentmethod. (required)

  • [].products.databrowser[].custom_fqdn[] (string) –

  • [].products.databrowser[].id (string) – (required)

  • [].products.databrowser[].name (string) –

  • [].products.databrowser[].size (string) –

  • [].products.databrowser[].type (string) – This is only set when the databrower is being used in a gdpr platform

  • [].products.datahub.backup (string) –

  • [].products.datahub.byok (boolean) – Setting this to true enables the “Bring Your Own Keys” feature in Azure. See this page for some background on the BYOK feature: https://docs.microsoft.com/en-us/azure/information-protection/byok-price-restrictions Note that enabling this feature incurs additional costs.

  • [].products.datahub.developer_mode (boolean) – This is a property that is set in some subscriptions to allow certain APIs such as reset node that is dangerous to enable in a production environment

  • [].products.datahub.fixed_price_gb (integer) – This property specifies the number of GBs that are set as the threshold for the subscription fixed price payment scheme. If this property exists, subscription is invoiced using fixed price scheme.

  • [].products.datahub.maximum_store_disk_usage (integer) – This is a read-only property that is set in some special cases where a custom server has been set up by sesam employees. It specifies the maximum size of the data store in bytes.

  • [].products.datahub.monitoring (string) – This can be set to “standard” to enable monitoring for this subscription (this currently requires some manual work by SESAM employees).

  • [].products.datahub.size (string) – This property describes the size of the node. As of Sep 2021, small, medium, large and xlarge are legacy sizes. The UI maps small/medium to single and xlarge to multi. (required)

  • [].products.datahub.version (string) – The docker tag that the user wants the sesam-node container to use. The docker tag that is currently in use is specified in the “provisioning_result”->”datahub”->”tag” property. There will always be a delay between the time the user changes the “version”-property and the time when the “provisioning_result”->”datahub”->”tag” property changes; at the very least the sesam-node needs to be stopped and restarted with the new docker-image.

  • [].products.gdpr_platform.custom_fqdn[] (string) –

  • [].products.gdpr_platform.name (string) – An optional, humanreadable name for this gdpr platform.

  • [].products.gdpr_platform.size (string) – (required)

  • [].products.microservices.size (string) – (required)

  • [].products.search (boolean) – This controls whether to activate the search capability

  • [].products.sla.level (string) – (required)

  • [].products.vpn.connections[]._id (integer) – This is an internal unique id that is assigned to new vpn-connections by the backend. The GUI will not display this value, but will include it as-is in PUT-requests. (The portal backend uses this value to replace the placeholder “****” for the shared_key property in PUT-requests; it needs a way to uniquely identify connections).

  • [].products.vpn.connections[].address_spaces[] (string) –

  • [].products.vpn.connections[].gateway_address (string) –

  • [].products.vpn.connections[].shared_key (string) – This is the secret shared key that is used to authenticate against the VPN. This property is write-only and will always look like “****” in the api-responses from the backend. If the special value “****” is used in a PUT-request, the value is ignored and the current shared_key value will not be changed. The intention is that the GUI can display and send the shared_key value as-is.

  • [].products.vpn.dns[] (string) –

  • [].products.vpn.enable_snat (boolean) –

  • [].products.vpn.local-range (string) –

  • [].products.vpn.local-subnet (string) –

  • [].products.vpn.onsite-ranges[] (string) –

  • [].products.vpn.public-gateway (string) –

  • [].products.vpn.sesam_address_spaces[] (string) –

  • [].products.vpn.sesam_gateway (string) –

  • [].products.vpn.tier (integer) –

  • [].products.vpn.type (string) –

  • [].provisioner_version (string) – Specifies the version of the sesam provisioner that’s been used to provision this subscription. As of now that can either be “1”, “2” or “snowflake”

  • [].provisioning_result.bootstrap (boolean) –

  • [].provisioning_result.datahub.debuginfo (any) – This property contains debug information that is only present in internal development environments.

  • [].provisioning_result.datahub.fqdn (string) – (required)

  • [].provisioning_result.datahub.private-ip (string) – (required)

  • [].provisioning_result.datahub.public_ip (string) – (required)

  • [].provisioning_result.datahub.tag (string) – The docker image tag that the sesam-node container is currently using.

  • [].provisioning_result.dev_docker_container_info (object) – This property contains debug information that is only present in internal development environments.

  • [].provisioning_result.msg[] (string) –

  • [].provisioning_result.network.acl[].access (string) – (required)

  • [].provisioning_result.network.acl[].address (string) – (required)

  • [].provisioning_result.network.public-access (boolean) –

  • [].provisioning_result.network.range (string) –

  • [].provisioning_result.network.subnet (string) –

  • [].provisioning_result.provisioning_settings.kubernets_upgrade_channel (string) – The upgrade channel to use to auto-upgrade the kubernetes cluster. See https://docs.microsoft.com/en-us/azure/aks/upgrade-cluster#set-auto-upgrade-channel for a detailed explanation and for a list of available channels.

  • [].provisioning_result.provisioning_settings.max_workers (integer) – The maximum number of server machines this subscription is allowed to use.

  • [].provisioning_result.provisioning_settings.num_workers (integer) – The number of server machines this subscription currently uses.

  • [].provisioning_result.services.databrowsers[].custom_fqdn[] (string) –

  • [].provisioning_result.services.databrowsers[].debuginfo (any) – This property contains debug information that is only present in internal development environments.

  • [].provisioning_result.services.databrowsers[].fqdn (string) – (required)

  • [].provisioning_result.services.databrowsers[].id (string) – (required)

  • [].provisioning_result.services.databrowsers[].private-ip (string) – (required)

  • [].provisioning_result.services.databrowsers[].public_ip (string) – (required)

  • [].provisioning_result.services.databrowsers[].size (string) –

  • [].provisioning_result.services.databrowsers[].tag (string) – The docker image tag for the data access portal container

  • [].provisioning_result.services.databrowsers[].type (string) – (required)

  • [].provisioning_status (string) –

  • [].service (string) – Specifies if the subscription is about in in-cloud or on-premise installation. This doesn’t have bearing on whether the Portal provisions this subscription or not, that is controlled by the provisioner_version property as of IS-10634. All on-premise subscriptions have provisioner_version “snowflake” and some in-cloud ones too.

  • [].supported-operations.accept_invitation (any) – (required)

  • [].supported-operations.add_api_jwt_token (any) –

  • [].supported-operations.add_notification_rule (any) – (required)

  • [].supported-operations.assign_role_to_user (any) – (required)

  • [].supported-operations.create_custom_role (any) – (required)

  • [].supported-operations.decline_invitation (any) – (required)

  • [].supported-operations.delete_subscription (any) – (required)

  • [].supported-operations.invite_user (any) – (required)

  • [].supported-operations.leave_subscription (any) – (required)

  • [].supported-operations.modify_subscription (any) – (required)

  • [].supported-operations.renew_license (any) –

  • [].supported-operations.view_api_jwt_tokens (any) –

  • [].supported-operations.view_members (any) – (required)

  • [].type (string) – This can be set to ‘trial’ in order to create a trial subscription. It is only legal to set this to true if the ‘create_trial_subscription’-operation (from the ‘supported-operations’ from /api/profile) is enabled and all the various ‘size’ and ‘level’ settings on the subscription is at their minimum values. (required)

  • [].url (string) – An URL that points to a web-page that is related to the subscription somehow. This url just for human consumption, and would typically be used to point to the home-page of a project, or a wiki-page that describes what the sesam-installation does.

  • [].was_created_from_a_precreated_subscription (boolean) – Specified if this subscription was create by assigning a precreated subscription.

POST /api/subscriptions

Creates a new subscription

Request JSON Object

  • connections[].id (string) – The name “id” is a special case; it represents the default sesam-node connection. When the item’s type is “databrowser”, the id refers to a databrowser in the “databrowser”-list in the “products”-part of the subscription info. (required)

  • connections[].name (string) – The human-redable name of the connection. (required)

  • connections[].type (string) – This specified the type of component this connection points to. (required)

  • connections[].url (string) – (required)

  • description (string) – A short description of the subscription.

  • id (string) –

  • license-expiration-date (string) – If this is specified it should be an ISO-8601 formatted datestring. This is used instead of the default value when setting the expiration date of the subscription license. The specified value cannot be in the past or too far in the future (a 400-response will be returned if the value is invalid).

  • name (string) –

  • network.network-acl[].access (string) – (required)

  • network.network-acl[].address (string) – (required)

  • network.public-access (boolean) –

  • paymentmethod_id (string) – The id of the PaymentMethod that the licence-fee for this subscription should be billed to. This property is only present for subscriptions of the type “paid”.

  • products.databrowser[].custom_fqdn[] (string) –

  • products.databrowser[].id (string) – (required)

  • products.databrowser[].name (string) –

  • products.databrowser[].size (string) –

  • products.databrowser[].type (string) – This is only set when the databrower is being used in a gdpr platform

  • products.datahub.backup (string) –

  • products.datahub.byok (boolean) – Setting this to true enables the “Bring Your Own Keys” feature in Azure. See this page for some background on the BYOK feature: https://docs.microsoft.com/en-us/azure/information-protection/byok-price-restrictions Note that enabling this feature incurs additional costs.

  • products.datahub.developer_mode (boolean) – This is a property that is set in some subscriptions to allow certain APIs such as reset node that is dangerous to enable in a production environment

  • products.datahub.fixed_price_gb (integer) – This property specifies the number of GBs that are set as the threshold for the subscription fixed price payment scheme. If this property exists, subscription is invoiced using fixed price scheme.

  • products.datahub.maximum_store_disk_usage (integer) – This is a read-only property that is set in some special cases where a custom server has been set up by sesam employees. It specifies the maximum size of the data store in bytes.

  • products.datahub.monitoring (string) – This can be set to “standard” to enable monitoring for this subscription (this currently requires some manual work by SESAM employees).

  • products.datahub.size (string) – This property describes the size of the node. As of Sep 2021, small, medium, large and xlarge are legacy sizes. The UI maps small/medium to single and xlarge to multi. (required)

  • products.datahub.version (string) – The docker tag that the user wants the sesam-node container to use. The docker tag that is currently in use is specified in the “provisioning_result”->”datahub”->”tag” property. There will always be a delay between the time the user changes the “version”-property and the time when the “provisioning_result”->”datahub”->”tag” property changes; at the very least the sesam-node needs to be stopped and restarted with the new docker-image.

  • products.gdpr_platform.custom_fqdn[] (string) –

  • products.gdpr_platform.name (string) – An optional, humanreadable name for this gdpr platform.

  • products.gdpr_platform.size (string) – (required)

  • products.microservices.size (string) – (required)

  • products.search (boolean) – This controls whether to activate the search capability

  • products.sla.level (string) – (required)

  • products.vpn.connections[]._id (integer) – This is an internal unique id that is assigned to new vpn-connections by the backend. The GUI will not display this value, but will include it as-is in PUT-requests. (The portal backend uses this value to replace the placeholder “****” for the shared_key property in PUT-requests; it needs a way to uniquely identify connections).

  • products.vpn.connections[].address_spaces[] (string) –

  • products.vpn.connections[].gateway_address (string) –

  • products.vpn.connections[].shared_key (string) – This is the secret shared key that is used to authenticate against the VPN. This property is write-only and will always look like “****” in the api-responses from the backend. If the special value “****” is used in a PUT-request, the value is ignored and the current shared_key value will not be changed. The intention is that the GUI can display and send the shared_key value as-is.

  • products.vpn.dns[] (string) –

  • products.vpn.enable_snat (boolean) –

  • products.vpn.local-range (string) –

  • products.vpn.local-subnet (string) –

  • products.vpn.onsite-ranges[] (string) –

  • products.vpn.public-gateway (string) –

  • products.vpn.sesam_address_spaces[] (string) –

  • products.vpn.sesam_gateway (string) –

  • products.vpn.tier (integer) –

  • products.vpn.type (string) –

  • provisioner_version (string) – This specified the provisioner this subscription will be provisioned with. If this value is “1” or missing, and the service specified is “in-cloud”, the original provisioner is used. If the value is “2”, the new “sesam-provisioner” is used. If the version is “snowflake” the Portal won’t provision this subscription.

  • service (string) – Specifies if the subscription is about in in-cloud or on-premise installation. This doesn’t have bearing on whether the Portal provisions this subscription or not, that is controlled by the provisioner_version property as of IS-10634. All on-premise subscriptions have provisioner_version “snowflake” and some in-cloud ones too.

  • type (string) – This can be set to ‘trial’ in order to create a trial subscription. It is only legal to set this to true if the ‘create_trial_subscription’-operation (from the ‘supported-operations’ from /api/profile) is enabled and all the various ‘size’ and ‘level’ settings on the subscription is at their minimum values.

  • url (string) – An URL that points to a web-page that is related to the subscription somehow. This url just for human consumption, and would typically be used to point to the home-page of a project, or a wiki-page that describes what the sesam-installation does.

Status Codes
Response JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • audit.created_by.email (string) –

  • audit.created_by.name (string) –

  • audit.created_by.picture (string) –

  • audit.created_by.user_id (string) –

  • audit.created_ts (string) –

  • audit.last_modified_by.email (string) –

  • audit.last_modified_by.name (string) –

  • audit.last_modified_by.picture (string) –

  • audit.last_modified_by.user_id (string) –

  • audit.last_modified_ts (string) –

  • connections[].id (string) – The name “id” is a special case; it represents the default sesam-node connection. When the item’s type is “databrowser”, the id refers to a databrowser in the “databrowser”-list in the “products”-part of the subscription info. (required)

  • connections[].name (string) – The human-redable name of the connection. (required)

  • connections[].type (string) – This specified the type of component this connection points to. (required)

  • connections[].url (string) – (required)

  • created (string) – (required)

  • current-users-member (any) –

  • description (string) – A short description of the subscription.

  • id (string) – (required)

  • is_unused_precreated_subscription (boolean) – Specified if this is an unused precreated subscription. Such subscriptions are kept in reserve and assigned to people when they try to create a new subscription. This saves people from having to wait for a new box to be provisioned.

  • licenses[].is-active-license (boolean) – This is set to true if this is the currently active license. A subscription might have several licenses; each license has an expiration date, and each time the customer will renews the license, a new entry is added to the subscription’s ‘licenses’ list.

  • licenses[].original._id (string) – (required)

  • licenses[].original.created (string) – (required)

  • licenses[].original.email (string) – (required)

  • licenses[].original.expires (string) – (required)

  • licenses[].signed (string) – The signed license key. This is only present for ‘on-premise’ subscriptions. For ‘in-cloud’ subscriptions the license-key is handled by the provisioner service and should never be shown to the customer.

  • name (string) – (required)

  • network.network-acl[].access (string) – (required)

  • network.network-acl[].address (string) – (required)

  • network.public-access (boolean) –

  • paymentmethod_id (string) – The id of the PaymentMethod that the licence-fee for this subscription should be billed to. This property is only present for subscriptions of the type “paid”.

  • paymentmethod_info.description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use. (required)

  • paymentmethod_info.id (string) – The internal id of this paymentmethod. (required)

  • paymentmethod_info.is_verified (boolean) – This is set to true when a Portal administrator (i.e a SESAM employee) has manually examined the payment information and checked that it is legitimate. Only portal administrators are allowed to change the value of this property. (required)

  • paymentmethod_info.name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use. (required)

  • paymentmethod_info.owner.email (string) – The email of the owner (required)

  • paymentmethod_info.owner.name (string) – The name of the owner (required)

  • paymentmethod_info.owner.picture (string) –

  • paymentmethod_info.owner.user_id (string) – The id of the owner (required)

  • paymentmethod_info.type (string) – The type of this paymentmethod. (required)

  • products.databrowser[].custom_fqdn[] (string) –

  • products.databrowser[].id (string) – (required)

  • products.databrowser[].name (string) –

  • products.databrowser[].size (string) –

  • products.databrowser[].type (string) – This is only set when the databrower is being used in a gdpr platform

  • products.datahub.backup (string) –

  • products.datahub.byok (boolean) – Setting this to true enables the “Bring Your Own Keys” feature in Azure. See this page for some background on the BYOK feature: https://docs.microsoft.com/en-us/azure/information-protection/byok-price-restrictions Note that enabling this feature incurs additional costs.

  • products.datahub.developer_mode (boolean) – This is a property that is set in some subscriptions to allow certain APIs such as reset node that is dangerous to enable in a production environment

  • products.datahub.fixed_price_gb (integer) – This property specifies the number of GBs that are set as the threshold for the subscription fixed price payment scheme. If this property exists, subscription is invoiced using fixed price scheme.

  • products.datahub.maximum_store_disk_usage (integer) – This is a read-only property that is set in some special cases where a custom server has been set up by sesam employees. It specifies the maximum size of the data store in bytes.

  • products.datahub.monitoring (string) – This can be set to “standard” to enable monitoring for this subscription (this currently requires some manual work by SESAM employees).

  • products.datahub.size (string) – This property describes the size of the node. As of Sep 2021, small, medium, large and xlarge are legacy sizes. The UI maps small/medium to single and xlarge to multi. (required)

  • products.datahub.version (string) – The docker tag that the user wants the sesam-node container to use. The docker tag that is currently in use is specified in the “provisioning_result”->”datahub”->”tag” property. There will always be a delay between the time the user changes the “version”-property and the time when the “provisioning_result”->”datahub”->”tag” property changes; at the very least the sesam-node needs to be stopped and restarted with the new docker-image.

  • products.gdpr_platform.custom_fqdn[] (string) –

  • products.gdpr_platform.name (string) – An optional, humanreadable name for this gdpr platform.

  • products.gdpr_platform.size (string) – (required)

  • products.microservices.size (string) – (required)

  • products.search (boolean) – This controls whether to activate the search capability

  • products.sla.level (string) – (required)

  • products.vpn.connections[]._id (integer) – This is an internal unique id that is assigned to new vpn-connections by the backend. The GUI will not display this value, but will include it as-is in PUT-requests. (The portal backend uses this value to replace the placeholder “****” for the shared_key property in PUT-requests; it needs a way to uniquely identify connections).

  • products.vpn.connections[].address_spaces[] (string) –

  • products.vpn.connections[].gateway_address (string) –

  • products.vpn.connections[].shared_key (string) – This is the secret shared key that is used to authenticate against the VPN. This property is write-only and will always look like “****” in the api-responses from the backend. If the special value “****” is used in a PUT-request, the value is ignored and the current shared_key value will not be changed. The intention is that the GUI can display and send the shared_key value as-is.

  • products.vpn.dns[] (string) –

  • products.vpn.enable_snat (boolean) –

  • products.vpn.local-range (string) –

  • products.vpn.local-subnet (string) –

  • products.vpn.onsite-ranges[] (string) –

  • products.vpn.public-gateway (string) –

  • products.vpn.sesam_address_spaces[] (string) –

  • products.vpn.sesam_gateway (string) –

  • products.vpn.tier (integer) –

  • products.vpn.type (string) –

  • provisioner_version (string) – Specifies the version of the sesam provisioner that’s been used to provision this subscription. As of now that can either be “1”, “2” or “snowflake”

  • provisioning_result.bootstrap (boolean) –

  • provisioning_result.datahub.debuginfo (any) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.datahub.fqdn (string) – (required)

  • provisioning_result.datahub.private-ip (string) – (required)

  • provisioning_result.datahub.public_ip (string) – (required)

  • provisioning_result.datahub.tag (string) – The docker image tag that the sesam-node container is currently using.

  • provisioning_result.dev_docker_container_info (object) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.msg[] (string) –

  • provisioning_result.network.acl[].access (string) – (required)

  • provisioning_result.network.acl[].address (string) – (required)

  • provisioning_result.network.public-access (boolean) –

  • provisioning_result.network.range (string) –

  • provisioning_result.network.subnet (string) –

  • provisioning_result.provisioning_settings.kubernets_upgrade_channel (string) – The upgrade channel to use to auto-upgrade the kubernetes cluster. See https://docs.microsoft.com/en-us/azure/aks/upgrade-cluster#set-auto-upgrade-channel for a detailed explanation and for a list of available channels.

  • provisioning_result.provisioning_settings.max_workers (integer) – The maximum number of server machines this subscription is allowed to use.

  • provisioning_result.provisioning_settings.num_workers (integer) – The number of server machines this subscription currently uses.

  • provisioning_result.services.databrowsers[].custom_fqdn[] (string) –

  • provisioning_result.services.databrowsers[].debuginfo (any) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.services.databrowsers[].fqdn (string) – (required)

  • provisioning_result.services.databrowsers[].id (string) – (required)

  • provisioning_result.services.databrowsers[].private-ip (string) – (required)

  • provisioning_result.services.databrowsers[].public_ip (string) – (required)

  • provisioning_result.services.databrowsers[].size (string) –

  • provisioning_result.services.databrowsers[].tag (string) – The docker image tag for the data access portal container

  • provisioning_result.services.databrowsers[].type (string) – (required)

  • provisioning_status (string) –

  • service (string) – Specifies if the subscription is about in in-cloud or on-premise installation. This doesn’t have bearing on whether the Portal provisions this subscription or not, that is controlled by the provisioner_version property as of IS-10634. All on-premise subscriptions have provisioner_version “snowflake” and some in-cloud ones too.

  • supported-operations.accept_invitation (any) – (required)

  • supported-operations.add_api_jwt_token (any) –

  • supported-operations.add_notification_rule (any) – (required)

  • supported-operations.assign_role_to_user (any) – (required)

  • supported-operations.create_custom_role (any) – (required)

  • supported-operations.decline_invitation (any) – (required)

  • supported-operations.delete_subscription (any) – (required)

  • supported-operations.invite_user (any) – (required)

  • supported-operations.leave_subscription (any) – (required)

  • supported-operations.modify_subscription (any) – (required)

  • supported-operations.renew_license (any) –

  • supported-operations.view_api_jwt_tokens (any) –

  • supported-operations.view_members (any) – (required)

  • type (string) – This can be set to ‘trial’ in order to create a trial subscription. It is only legal to set this to true if the ‘create_trial_subscription’-operation (from the ‘supported-operations’ from /api/profile) is enabled and all the various ‘size’ and ‘level’ settings on the subscription is at their minimum values. (required)

  • url (string) – An URL that points to a web-page that is related to the subscription somehow. This url just for human consumption, and would typically be used to point to the home-page of a project, or a wiki-page that describes what the sesam-installation does.

  • was_created_from_a_precreated_subscription (boolean) – Specified if this subscription was create by assigning a precreated subscription.

GET /api/subscriptions/{subscription_id}

Returns information about the specified subscription

Parameters

  • subscription_id (string) – The subscription id

Status Codes
Response JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • audit.created_by.email (string) –

  • audit.created_by.name (string) –

  • audit.created_by.picture (string) –

  • audit.created_by.user_id (string) –

  • audit.created_ts (string) –

  • audit.last_modified_by.email (string) –

  • audit.last_modified_by.name (string) –

  • audit.last_modified_by.picture (string) –

  • audit.last_modified_by.user_id (string) –

  • audit.last_modified_ts (string) –

  • connections[].id (string) – The name “id” is a special case; it represents the default sesam-node connection. When the item’s type is “databrowser”, the id refers to a databrowser in the “databrowser”-list in the “products”-part of the subscription info. (required)

  • connections[].name (string) – The human-redable name of the connection. (required)

  • connections[].type (string) – This specified the type of component this connection points to. (required)

  • connections[].url (string) – (required)

  • created (string) – (required)

  • current-users-member (any) –

  • description (string) – A short description of the subscription.

  • id (string) – (required)

  • is_unused_precreated_subscription (boolean) – Specified if this is an unused precreated subscription. Such subscriptions are kept in reserve and assigned to people when they try to create a new subscription. This saves people from having to wait for a new box to be provisioned.

  • licenses[].is-active-license (boolean) – This is set to true if this is the currently active license. A subscription might have several licenses; each license has an expiration date, and each time the customer will renews the license, a new entry is added to the subscription’s ‘licenses’ list.

  • licenses[].original._id (string) – (required)

  • licenses[].original.created (string) – (required)

  • licenses[].original.email (string) – (required)

  • licenses[].original.expires (string) – (required)

  • licenses[].signed (string) – The signed license key. This is only present for ‘on-premise’ subscriptions. For ‘in-cloud’ subscriptions the license-key is handled by the provisioner service and should never be shown to the customer.

  • name (string) – (required)

  • network.network-acl[].access (string) – (required)

  • network.network-acl[].address (string) – (required)

  • network.public-access (boolean) –

  • paymentmethod_id (string) – The id of the PaymentMethod that the licence-fee for this subscription should be billed to. This property is only present for subscriptions of the type “paid”.

  • paymentmethod_info.description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use. (required)

  • paymentmethod_info.id (string) – The internal id of this paymentmethod. (required)

  • paymentmethod_info.is_verified (boolean) – This is set to true when a Portal administrator (i.e a SESAM employee) has manually examined the payment information and checked that it is legitimate. Only portal administrators are allowed to change the value of this property. (required)

  • paymentmethod_info.name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use. (required)

  • paymentmethod_info.owner.email (string) – The email of the owner (required)

  • paymentmethod_info.owner.name (string) – The name of the owner (required)

  • paymentmethod_info.owner.picture (string) –

  • paymentmethod_info.owner.user_id (string) – The id of the owner (required)

  • paymentmethod_info.type (string) – The type of this paymentmethod. (required)

  • products.databrowser[].custom_fqdn[] (string) –

  • products.databrowser[].id (string) – (required)

  • products.databrowser[].name (string) –

  • products.databrowser[].size (string) –

  • products.databrowser[].type (string) – This is only set when the databrower is being used in a gdpr platform

  • products.datahub.backup (string) –

  • products.datahub.byok (boolean) – Setting this to true enables the “Bring Your Own Keys” feature in Azure. See this page for some background on the BYOK feature: https://docs.microsoft.com/en-us/azure/information-protection/byok-price-restrictions Note that enabling this feature incurs additional costs.

  • products.datahub.developer_mode (boolean) – This is a property that is set in some subscriptions to allow certain APIs such as reset node that is dangerous to enable in a production environment

  • products.datahub.fixed_price_gb (integer) – This property specifies the number of GBs that are set as the threshold for the subscription fixed price payment scheme. If this property exists, subscription is invoiced using fixed price scheme.

  • products.datahub.maximum_store_disk_usage (integer) – This is a read-only property that is set in some special cases where a custom server has been set up by sesam employees. It specifies the maximum size of the data store in bytes.

  • products.datahub.monitoring (string) – This can be set to “standard” to enable monitoring for this subscription (this currently requires some manual work by SESAM employees).

  • products.datahub.size (string) – This property describes the size of the node. As of Sep 2021, small, medium, large and xlarge are legacy sizes. The UI maps small/medium to single and xlarge to multi. (required)

  • products.datahub.version (string) – The docker tag that the user wants the sesam-node container to use. The docker tag that is currently in use is specified in the “provisioning_result”->”datahub”->”tag” property. There will always be a delay between the time the user changes the “version”-property and the time when the “provisioning_result”->”datahub”->”tag” property changes; at the very least the sesam-node needs to be stopped and restarted with the new docker-image.

  • products.gdpr_platform.custom_fqdn[] (string) –

  • products.gdpr_platform.name (string) – An optional, humanreadable name for this gdpr platform.

  • products.gdpr_platform.size (string) – (required)

  • products.microservices.size (string) – (required)

  • products.search (boolean) – This controls whether to activate the search capability

  • products.sla.level (string) – (required)

  • products.vpn.connections[]._id (integer) – This is an internal unique id that is assigned to new vpn-connections by the backend. The GUI will not display this value, but will include it as-is in PUT-requests. (The portal backend uses this value to replace the placeholder “****” for the shared_key property in PUT-requests; it needs a way to uniquely identify connections).

  • products.vpn.connections[].address_spaces[] (string) –

  • products.vpn.connections[].gateway_address (string) –

  • products.vpn.connections[].shared_key (string) – This is the secret shared key that is used to authenticate against the VPN. This property is write-only and will always look like “****” in the api-responses from the backend. If the special value “****” is used in a PUT-request, the value is ignored and the current shared_key value will not be changed. The intention is that the GUI can display and send the shared_key value as-is.

  • products.vpn.dns[] (string) –

  • products.vpn.enable_snat (boolean) –

  • products.vpn.local-range (string) –

  • products.vpn.local-subnet (string) –

  • products.vpn.onsite-ranges[] (string) –

  • products.vpn.public-gateway (string) –

  • products.vpn.sesam_address_spaces[] (string) –

  • products.vpn.sesam_gateway (string) –

  • products.vpn.tier (integer) –

  • products.vpn.type (string) –

  • provisioner_version (string) – Specifies the version of the sesam provisioner that’s been used to provision this subscription. As of now that can either be “1”, “2” or “snowflake”

  • provisioning_result.bootstrap (boolean) –

  • provisioning_result.datahub.debuginfo (any) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.datahub.fqdn (string) – (required)

  • provisioning_result.datahub.private-ip (string) – (required)

  • provisioning_result.datahub.public_ip (string) – (required)

  • provisioning_result.datahub.tag (string) – The docker image tag that the sesam-node container is currently using.

  • provisioning_result.dev_docker_container_info (object) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.msg[] (string) –

  • provisioning_result.network.acl[].access (string) – (required)

  • provisioning_result.network.acl[].address (string) – (required)

  • provisioning_result.network.public-access (boolean) –

  • provisioning_result.network.range (string) –

  • provisioning_result.network.subnet (string) –

  • provisioning_result.provisioning_settings.kubernets_upgrade_channel (string) – The upgrade channel to use to auto-upgrade the kubernetes cluster. See https://docs.microsoft.com/en-us/azure/aks/upgrade-cluster#set-auto-upgrade-channel for a detailed explanation and for a list of available channels.

  • provisioning_result.provisioning_settings.max_workers (integer) – The maximum number of server machines this subscription is allowed to use.

  • provisioning_result.provisioning_settings.num_workers (integer) – The number of server machines this subscription currently uses.

  • provisioning_result.services.databrowsers[].custom_fqdn[] (string) –

  • provisioning_result.services.databrowsers[].debuginfo (any) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.services.databrowsers[].fqdn (string) – (required)

  • provisioning_result.services.databrowsers[].id (string) – (required)

  • provisioning_result.services.databrowsers[].private-ip (string) – (required)

  • provisioning_result.services.databrowsers[].public_ip (string) – (required)

  • provisioning_result.services.databrowsers[].size (string) –

  • provisioning_result.services.databrowsers[].tag (string) – The docker image tag for the data access portal container

  • provisioning_result.services.databrowsers[].type (string) – (required)

  • provisioning_status (string) –

  • service (string) – Specifies if the subscription is about in in-cloud or on-premise installation. This doesn’t have bearing on whether the Portal provisions this subscription or not, that is controlled by the provisioner_version property as of IS-10634. All on-premise subscriptions have provisioner_version “snowflake” and some in-cloud ones too.

  • supported-operations.accept_invitation (any) – (required)

  • supported-operations.add_api_jwt_token (any) –

  • supported-operations.add_notification_rule (any) – (required)

  • supported-operations.assign_role_to_user (any) – (required)

  • supported-operations.create_custom_role (any) – (required)

  • supported-operations.decline_invitation (any) – (required)

  • supported-operations.delete_subscription (any) – (required)

  • supported-operations.invite_user (any) – (required)

  • supported-operations.leave_subscription (any) – (required)

  • supported-operations.modify_subscription (any) – (required)

  • supported-operations.renew_license (any) –

  • supported-operations.view_api_jwt_tokens (any) –

  • supported-operations.view_members (any) – (required)

  • type (string) – This can be set to ‘trial’ in order to create a trial subscription. It is only legal to set this to true if the ‘create_trial_subscription’-operation (from the ‘supported-operations’ from /api/profile) is enabled and all the various ‘size’ and ‘level’ settings on the subscription is at their minimum values. (required)

  • url (string) – An URL that points to a web-page that is related to the subscription somehow. This url just for human consumption, and would typically be used to point to the home-page of a project, or a wiki-page that describes what the sesam-installation does.

  • was_created_from_a_precreated_subscription (boolean) – Specified if this subscription was create by assigning a precreated subscription.

DELETE /api/subscriptions/{subscription_id}

Deletes the specified subscription

Parameters

  • subscription_id (string) – The subscription id

Status Codes
PUT /api/subscriptions/{subscription_id}

Update the subscription

Parameters

  • subscription_id (string) – The subscription id

Request JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • connections[].id (string) – The name “id” is a special case; it represents the default sesam-node connection. When the item’s type is “databrowser”, the id refers to a databrowser in the “databrowser”-list in the “products”-part of the subscription info. (required)

  • connections[].name (string) – The human-redable name of the connection. (required)

  • connections[].type (string) – This specified the type of component this connection points to. (required)

  • connections[].url (string) – (required)

  • description (string) – A short description of the subscription.

  • name (string) –

  • network.network-acl[].access (string) – (required)

  • network.network-acl[].address (string) – (required)

  • network.public-access (boolean) –

  • paymentmethod_id (string) – The id of the PaymentMethod that the licence-fee for this subscription should be billed to. This property is only present for subscriptions of the type “paid”.

  • products.databrowser[].custom_fqdn[] (string) –

  • products.databrowser[].id (string) – (required)

  • products.databrowser[].name (string) –

  • products.databrowser[].size (string) –

  • products.databrowser[].type (string) – This is only set when the databrower is being used in a gdpr platform

  • products.datahub.backup (string) –

  • products.datahub.byok (boolean) – Setting this to true enables the “Bring Your Own Keys” feature in Azure. See this page for some background on the BYOK feature: https://docs.microsoft.com/en-us/azure/information-protection/byok-price-restrictions Note that enabling this feature incurs additional costs.

  • products.datahub.developer_mode (boolean) – This is a property that is set in some subscriptions to allow certain APIs such as reset node that is dangerous to enable in a production environment

  • products.datahub.fixed_price_gb (integer) – This property specifies the number of GBs that are set as the threshold for the subscription fixed price payment scheme. If this property exists, subscription is invoiced using fixed price scheme.

  • products.datahub.maximum_store_disk_usage (integer) – This is a read-only property that is set in some special cases where a custom server has been set up by sesam employees. It specifies the maximum size of the data store in bytes.

  • products.datahub.monitoring (string) – This can be set to “standard” to enable monitoring for this subscription (this currently requires some manual work by SESAM employees).

  • products.datahub.size (string) – This property describes the size of the node. As of Sep 2021, small, medium, large and xlarge are legacy sizes. The UI maps small/medium to single and xlarge to multi. (required)

  • products.datahub.version (string) – The docker tag that the user wants the sesam-node container to use. The docker tag that is currently in use is specified in the “provisioning_result”->”datahub”->”tag” property. There will always be a delay between the time the user changes the “version”-property and the time when the “provisioning_result”->”datahub”->”tag” property changes; at the very least the sesam-node needs to be stopped and restarted with the new docker-image.

  • products.gdpr_platform.custom_fqdn[] (string) –

  • products.gdpr_platform.name (string) – An optional, humanreadable name for this gdpr platform.

  • products.gdpr_platform.size (string) – (required)

  • products.microservices.size (string) – (required)

  • products.search (boolean) – This controls whether to activate the search capability

  • products.sla.level (string) – (required)

  • products.vpn.connections[]._id (integer) – This is an internal unique id that is assigned to new vpn-connections by the backend. The GUI will not display this value, but will include it as-is in PUT-requests. (The portal backend uses this value to replace the placeholder “****” for the shared_key property in PUT-requests; it needs a way to uniquely identify connections).

  • products.vpn.connections[].address_spaces[] (string) –

  • products.vpn.connections[].gateway_address (string) –

  • products.vpn.connections[].shared_key (string) – This is the secret shared key that is used to authenticate against the VPN. This property is write-only and will always look like “****” in the api-responses from the backend. If the special value “****” is used in a PUT-request, the value is ignored and the current shared_key value will not be changed. The intention is that the GUI can display and send the shared_key value as-is.

  • products.vpn.dns[] (string) –

  • products.vpn.enable_snat (boolean) –

  • products.vpn.local-range (string) –

  • products.vpn.local-subnet (string) –

  • products.vpn.onsite-ranges[] (string) –

  • products.vpn.public-gateway (string) –

  • products.vpn.sesam_address_spaces[] (string) –

  • products.vpn.sesam_gateway (string) –

  • products.vpn.tier (integer) –

  • products.vpn.type (string) –

  • url (string) – An URL that points to a web-page that is related to the subscription somehow. This url just for human consumption, and would typically be used to point to the home-page of a project, or a wiki-page that describes what the sesam-installation does.

Status Codes
Response JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • audit.created_by.email (string) –

  • audit.created_by.name (string) –

  • audit.created_by.picture (string) –

  • audit.created_by.user_id (string) –

  • audit.created_ts (string) –

  • audit.last_modified_by.email (string) –

  • audit.last_modified_by.name (string) –

  • audit.last_modified_by.picture (string) –

  • audit.last_modified_by.user_id (string) –

  • audit.last_modified_ts (string) –

  • connections[].id (string) – The name “id” is a special case; it represents the default sesam-node connection. When the item’s type is “databrowser”, the id refers to a databrowser in the “databrowser”-list in the “products”-part of the subscription info. (required)

  • connections[].name (string) – The human-redable name of the connection. (required)

  • connections[].type (string) – This specified the type of component this connection points to. (required)

  • connections[].url (string) – (required)

  • created (string) – (required)

  • current-users-member (any) –

  • description (string) – A short description of the subscription.

  • id (string) – (required)

  • is_unused_precreated_subscription (boolean) – Specified if this is an unused precreated subscription. Such subscriptions are kept in reserve and assigned to people when they try to create a new subscription. This saves people from having to wait for a new box to be provisioned.

  • licenses[].is-active-license (boolean) – This is set to true if this is the currently active license. A subscription might have several licenses; each license has an expiration date, and each time the customer will renews the license, a new entry is added to the subscription’s ‘licenses’ list.

  • licenses[].original._id (string) – (required)

  • licenses[].original.created (string) – (required)

  • licenses[].original.email (string) – (required)

  • licenses[].original.expires (string) – (required)

  • licenses[].signed (string) – The signed license key. This is only present for ‘on-premise’ subscriptions. For ‘in-cloud’ subscriptions the license-key is handled by the provisioner service and should never be shown to the customer.

  • name (string) – (required)

  • network.network-acl[].access (string) – (required)

  • network.network-acl[].address (string) – (required)

  • network.public-access (boolean) –

  • paymentmethod_id (string) – The id of the PaymentMethod that the licence-fee for this subscription should be billed to. This property is only present for subscriptions of the type “paid”.

  • paymentmethod_info.description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use. (required)

  • paymentmethod_info.id (string) – The internal id of this paymentmethod. (required)

  • paymentmethod_info.is_verified (boolean) – This is set to true when a Portal administrator (i.e a SESAM employee) has manually examined the payment information and checked that it is legitimate. Only portal administrators are allowed to change the value of this property. (required)

  • paymentmethod_info.name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use. (required)

  • paymentmethod_info.owner.email (string) – The email of the owner (required)

  • paymentmethod_info.owner.name (string) – The name of the owner (required)

  • paymentmethod_info.owner.picture (string) –

  • paymentmethod_info.owner.user_id (string) – The id of the owner (required)

  • paymentmethod_info.type (string) – The type of this paymentmethod. (required)

  • products.databrowser[].custom_fqdn[] (string) –

  • products.databrowser[].id (string) – (required)

  • products.databrowser[].name (string) –

  • products.databrowser[].size (string) –

  • products.databrowser[].type (string) – This is only set when the databrower is being used in a gdpr platform

  • products.datahub.backup (string) –

  • products.datahub.byok (boolean) – Setting this to true enables the “Bring Your Own Keys” feature in Azure. See this page for some background on the BYOK feature: https://docs.microsoft.com/en-us/azure/information-protection/byok-price-restrictions Note that enabling this feature incurs additional costs.

  • products.datahub.developer_mode (boolean) – This is a property that is set in some subscriptions to allow certain APIs such as reset node that is dangerous to enable in a production environment

  • products.datahub.fixed_price_gb (integer) – This property specifies the number of GBs that are set as the threshold for the subscription fixed price payment scheme. If this property exists, subscription is invoiced using fixed price scheme.

  • products.datahub.maximum_store_disk_usage (integer) – This is a read-only property that is set in some special cases where a custom server has been set up by sesam employees. It specifies the maximum size of the data store in bytes.

  • products.datahub.monitoring (string) – This can be set to “standard” to enable monitoring for this subscription (this currently requires some manual work by SESAM employees).

  • products.datahub.size (string) – This property describes the size of the node. As of Sep 2021, small, medium, large and xlarge are legacy sizes. The UI maps small/medium to single and xlarge to multi. (required)

  • products.datahub.version (string) – The docker tag that the user wants the sesam-node container to use. The docker tag that is currently in use is specified in the “provisioning_result”->”datahub”->”tag” property. There will always be a delay between the time the user changes the “version”-property and the time when the “provisioning_result”->”datahub”->”tag” property changes; at the very least the sesam-node needs to be stopped and restarted with the new docker-image.

  • products.gdpr_platform.custom_fqdn[] (string) –

  • products.gdpr_platform.name (string) – An optional, humanreadable name for this gdpr platform.

  • products.gdpr_platform.size (string) – (required)

  • products.microservices.size (string) – (required)

  • products.search (boolean) – This controls whether to activate the search capability

  • products.sla.level (string) – (required)

  • products.vpn.connections[]._id (integer) – This is an internal unique id that is assigned to new vpn-connections by the backend. The GUI will not display this value, but will include it as-is in PUT-requests. (The portal backend uses this value to replace the placeholder “****” for the shared_key property in PUT-requests; it needs a way to uniquely identify connections).

  • products.vpn.connections[].address_spaces[] (string) –

  • products.vpn.connections[].gateway_address (string) –

  • products.vpn.connections[].shared_key (string) – This is the secret shared key that is used to authenticate against the VPN. This property is write-only and will always look like “****” in the api-responses from the backend. If the special value “****” is used in a PUT-request, the value is ignored and the current shared_key value will not be changed. The intention is that the GUI can display and send the shared_key value as-is.

  • products.vpn.dns[] (string) –

  • products.vpn.enable_snat (boolean) –

  • products.vpn.local-range (string) –

  • products.vpn.local-subnet (string) –

  • products.vpn.onsite-ranges[] (string) –

  • products.vpn.public-gateway (string) –

  • products.vpn.sesam_address_spaces[] (string) –

  • products.vpn.sesam_gateway (string) –

  • products.vpn.tier (integer) –

  • products.vpn.type (string) –

  • provisioner_version (string) – Specifies the version of the sesam provisioner that’s been used to provision this subscription. As of now that can either be “1”, “2” or “snowflake”

  • provisioning_result.bootstrap (boolean) –

  • provisioning_result.datahub.debuginfo (any) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.datahub.fqdn (string) – (required)

  • provisioning_result.datahub.private-ip (string) – (required)

  • provisioning_result.datahub.public_ip (string) – (required)

  • provisioning_result.datahub.tag (string) – The docker image tag that the sesam-node container is currently using.

  • provisioning_result.dev_docker_container_info (object) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.msg[] (string) –

  • provisioning_result.network.acl[].access (string) – (required)

  • provisioning_result.network.acl[].address (string) – (required)

  • provisioning_result.network.public-access (boolean) –

  • provisioning_result.network.range (string) –

  • provisioning_result.network.subnet (string) –

  • provisioning_result.provisioning_settings.kubernets_upgrade_channel (string) – The upgrade channel to use to auto-upgrade the kubernetes cluster. See https://docs.microsoft.com/en-us/azure/aks/upgrade-cluster#set-auto-upgrade-channel for a detailed explanation and for a list of available channels.

  • provisioning_result.provisioning_settings.max_workers (integer) – The maximum number of server machines this subscription is allowed to use.

  • provisioning_result.provisioning_settings.num_workers (integer) – The number of server machines this subscription currently uses.

  • provisioning_result.services.databrowsers[].custom_fqdn[] (string) –

  • provisioning_result.services.databrowsers[].debuginfo (any) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.services.databrowsers[].fqdn (string) – (required)

  • provisioning_result.services.databrowsers[].id (string) – (required)

  • provisioning_result.services.databrowsers[].private-ip (string) – (required)

  • provisioning_result.services.databrowsers[].public_ip (string) – (required)

  • provisioning_result.services.databrowsers[].size (string) –

  • provisioning_result.services.databrowsers[].tag (string) – The docker image tag for the data access portal container

  • provisioning_result.services.databrowsers[].type (string) – (required)

  • provisioning_status (string) –

  • service (string) – Specifies if the subscription is about in in-cloud or on-premise installation. This doesn’t have bearing on whether the Portal provisions this subscription or not, that is controlled by the provisioner_version property as of IS-10634. All on-premise subscriptions have provisioner_version “snowflake” and some in-cloud ones too.

  • supported-operations.accept_invitation (any) – (required)

  • supported-operations.add_api_jwt_token (any) –

  • supported-operations.add_notification_rule (any) – (required)

  • supported-operations.assign_role_to_user (any) – (required)

  • supported-operations.create_custom_role (any) – (required)

  • supported-operations.decline_invitation (any) – (required)

  • supported-operations.delete_subscription (any) – (required)

  • supported-operations.invite_user (any) – (required)

  • supported-operations.leave_subscription (any) – (required)

  • supported-operations.modify_subscription (any) – (required)

  • supported-operations.renew_license (any) –

  • supported-operations.view_api_jwt_tokens (any) –

  • supported-operations.view_members (any) – (required)

  • type (string) – This can be set to ‘trial’ in order to create a trial subscription. It is only legal to set this to true if the ‘create_trial_subscription’-operation (from the ‘supported-operations’ from /api/profile) is enabled and all the various ‘size’ and ‘level’ settings on the subscription is at their minimum values. (required)

  • url (string) – An URL that points to a web-page that is related to the subscription somehow. This url just for human consumption, and would typically be used to point to the home-page of a project, or a wiki-page that describes what the sesam-installation does.

  • was_created_from_a_precreated_subscription (boolean) – Specified if this subscription was create by assigning a precreated subscription.

GET /api/subscriptions/{subscription_id}/available-roles

Returns a list of the roles that are available for the specified subscription. This includes the build-in roles and any custom-roles that has been created in the subscription.

Parameters

  • subscription_id (string) – The subscription id

Status Codes
Response JSON Object

  • [].child-roles[] (string) –

  • [].description (string) – A longer description of the role. The gui can use this for tooltips.

  • [].id (string) – The internal id of the role.

  • [].name (string) – A human readable name for the role. This is what the gui displays.

POST /api/subscriptions/{subscription_id}/available-roles

Adds a new custom-role.

Parameters

  • subscription_id (string) – The subscription id

Request JSON Object

  • child-roles[] (string) –

  • description (string) – A longer description of the role. The gui can use this for tooltips.

  • id (string) – The internal id of the role.

  • name (string) – A human readable name for the role. This is what the gui displays.

Status Codes
Response JSON Object

  • child-roles[] (string) –

  • description (string) – A longer description of the role. The gui can use this for tooltips.

  • id (string) – The internal id of the role.

  • name (string) – A human readable name for the role. This is what the gui displays.

POST /api/subscriptions/{subscription_id}/licenses

Renews the subscription’s license. This extends the current license’s expirationdate, but keeps all other license-values the same. Returns the updated Subscription.

Parameters

  • subscription_id (string) – The subscription id

Status Codes
Response JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • audit.created_by.email (string) –

  • audit.created_by.name (string) –

  • audit.created_by.picture (string) –

  • audit.created_by.user_id (string) –

  • audit.created_ts (string) –

  • audit.last_modified_by.email (string) –

  • audit.last_modified_by.name (string) –

  • audit.last_modified_by.picture (string) –

  • audit.last_modified_by.user_id (string) –

  • audit.last_modified_ts (string) –

  • connections[].id (string) – The name “id” is a special case; it represents the default sesam-node connection. When the item’s type is “databrowser”, the id refers to a databrowser in the “databrowser”-list in the “products”-part of the subscription info. (required)

  • connections[].name (string) – The human-redable name of the connection. (required)

  • connections[].type (string) – This specified the type of component this connection points to. (required)

  • connections[].url (string) – (required)

  • created (string) – (required)

  • current-users-member (any) –

  • description (string) – A short description of the subscription.

  • id (string) – (required)

  • is_unused_precreated_subscription (boolean) – Specified if this is an unused precreated subscription. Such subscriptions are kept in reserve and assigned to people when they try to create a new subscription. This saves people from having to wait for a new box to be provisioned.

  • licenses[].is-active-license (boolean) – This is set to true if this is the currently active license. A subscription might have several licenses; each license has an expiration date, and each time the customer will renews the license, a new entry is added to the subscription’s ‘licenses’ list.

  • licenses[].original._id (string) – (required)

  • licenses[].original.created (string) – (required)

  • licenses[].original.email (string) – (required)

  • licenses[].original.expires (string) – (required)

  • licenses[].signed (string) – The signed license key. This is only present for ‘on-premise’ subscriptions. For ‘in-cloud’ subscriptions the license-key is handled by the provisioner service and should never be shown to the customer.

  • name (string) – (required)

  • network.network-acl[].access (string) – (required)

  • network.network-acl[].address (string) – (required)

  • network.public-access (boolean) –

  • paymentmethod_id (string) – The id of the PaymentMethod that the licence-fee for this subscription should be billed to. This property is only present for subscriptions of the type “paid”.

  • paymentmethod_info.description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use. (required)

  • paymentmethod_info.id (string) – The internal id of this paymentmethod. (required)

  • paymentmethod_info.is_verified (boolean) – This is set to true when a Portal administrator (i.e a SESAM employee) has manually examined the payment information and checked that it is legitimate. Only portal administrators are allowed to change the value of this property. (required)

  • paymentmethod_info.name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use. (required)

  • paymentmethod_info.owner.email (string) – The email of the owner (required)

  • paymentmethod_info.owner.name (string) – The name of the owner (required)

  • paymentmethod_info.owner.picture (string) –

  • paymentmethod_info.owner.user_id (string) – The id of the owner (required)

  • paymentmethod_info.type (string) – The type of this paymentmethod. (required)

  • products.databrowser[].custom_fqdn[] (string) –

  • products.databrowser[].id (string) – (required)

  • products.databrowser[].name (string) –

  • products.databrowser[].size (string) –

  • products.databrowser[].type (string) – This is only set when the databrower is being used in a gdpr platform

  • products.datahub.backup (string) –

  • products.datahub.byok (boolean) – Setting this to true enables the “Bring Your Own Keys” feature in Azure. See this page for some background on the BYOK feature: https://docs.microsoft.com/en-us/azure/information-protection/byok-price-restrictions Note that enabling this feature incurs additional costs.

  • products.datahub.developer_mode (boolean) – This is a property that is set in some subscriptions to allow certain APIs such as reset node that is dangerous to enable in a production environment

  • products.datahub.fixed_price_gb (integer) – This property specifies the number of GBs that are set as the threshold for the subscription fixed price payment scheme. If this property exists, subscription is invoiced using fixed price scheme.

  • products.datahub.maximum_store_disk_usage (integer) – This is a read-only property that is set in some special cases where a custom server has been set up by sesam employees. It specifies the maximum size of the data store in bytes.

  • products.datahub.monitoring (string) – This can be set to “standard” to enable monitoring for this subscription (this currently requires some manual work by SESAM employees).

  • products.datahub.size (string) – This property describes the size of the node. As of Sep 2021, small, medium, large and xlarge are legacy sizes. The UI maps small/medium to single and xlarge to multi. (required)

  • products.datahub.version (string) – The docker tag that the user wants the sesam-node container to use. The docker tag that is currently in use is specified in the “provisioning_result”->”datahub”->”tag” property. There will always be a delay between the time the user changes the “version”-property and the time when the “provisioning_result”->”datahub”->”tag” property changes; at the very least the sesam-node needs to be stopped and restarted with the new docker-image.

  • products.gdpr_platform.custom_fqdn[] (string) –

  • products.gdpr_platform.name (string) – An optional, humanreadable name for this gdpr platform.

  • products.gdpr_platform.size (string) – (required)

  • products.microservices.size (string) – (required)

  • products.search (boolean) – This controls whether to activate the search capability

  • products.sla.level (string) – (required)

  • products.vpn.connections[]._id (integer) – This is an internal unique id that is assigned to new vpn-connections by the backend. The GUI will not display this value, but will include it as-is in PUT-requests. (The portal backend uses this value to replace the placeholder “****” for the shared_key property in PUT-requests; it needs a way to uniquely identify connections).

  • products.vpn.connections[].address_spaces[] (string) –

  • products.vpn.connections[].gateway_address (string) –

  • products.vpn.connections[].shared_key (string) – This is the secret shared key that is used to authenticate against the VPN. This property is write-only and will always look like “****” in the api-responses from the backend. If the special value “****” is used in a PUT-request, the value is ignored and the current shared_key value will not be changed. The intention is that the GUI can display and send the shared_key value as-is.

  • products.vpn.dns[] (string) –

  • products.vpn.enable_snat (boolean) –

  • products.vpn.local-range (string) –

  • products.vpn.local-subnet (string) –

  • products.vpn.onsite-ranges[] (string) –

  • products.vpn.public-gateway (string) –

  • products.vpn.sesam_address_spaces[] (string) –

  • products.vpn.sesam_gateway (string) –

  • products.vpn.tier (integer) –

  • products.vpn.type (string) –

  • provisioner_version (string) – Specifies the version of the sesam provisioner that’s been used to provision this subscription. As of now that can either be “1”, “2” or “snowflake”

  • provisioning_result.bootstrap (boolean) –

  • provisioning_result.datahub.debuginfo (any) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.datahub.fqdn (string) – (required)

  • provisioning_result.datahub.private-ip (string) – (required)

  • provisioning_result.datahub.public_ip (string) – (required)

  • provisioning_result.datahub.tag (string) – The docker image tag that the sesam-node container is currently using.

  • provisioning_result.dev_docker_container_info (object) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.msg[] (string) –

  • provisioning_result.network.acl[].access (string) – (required)

  • provisioning_result.network.acl[].address (string) – (required)

  • provisioning_result.network.public-access (boolean) –

  • provisioning_result.network.range (string) –

  • provisioning_result.network.subnet (string) –

  • provisioning_result.provisioning_settings.kubernets_upgrade_channel (string) – The upgrade channel to use to auto-upgrade the kubernetes cluster. See https://docs.microsoft.com/en-us/azure/aks/upgrade-cluster#set-auto-upgrade-channel for a detailed explanation and for a list of available channels.

  • provisioning_result.provisioning_settings.max_workers (integer) – The maximum number of server machines this subscription is allowed to use.

  • provisioning_result.provisioning_settings.num_workers (integer) – The number of server machines this subscription currently uses.

  • provisioning_result.services.databrowsers[].custom_fqdn[] (string) –

  • provisioning_result.services.databrowsers[].debuginfo (any) – This property contains debug information that is only present in internal development environments.

  • provisioning_result.services.databrowsers[].fqdn (string) – (required)

  • provisioning_result.services.databrowsers[].id (string) – (required)

  • provisioning_result.services.databrowsers[].private-ip (string) – (required)

  • provisioning_result.services.databrowsers[].public_ip (string) – (required)

  • provisioning_result.services.databrowsers[].size (string) –

  • provisioning_result.services.databrowsers[].tag (string) – The docker image tag for the data access portal container

  • provisioning_result.services.databrowsers[].type (string) – (required)

  • provisioning_status (string) –

  • service (string) – Specifies if the subscription is about in in-cloud or on-premise installation. This doesn’t have bearing on whether the Portal provisions this subscription or not, that is controlled by the provisioner_version property as of IS-10634. All on-premise subscriptions have provisioner_version “snowflake” and some in-cloud ones too.

  • supported-operations.accept_invitation (any) – (required)

  • supported-operations.add_api_jwt_token (any) –

  • supported-operations.add_notification_rule (any) – (required)

  • supported-operations.assign_role_to_user (any) – (required)

  • supported-operations.create_custom_role (any) – (required)

  • supported-operations.decline_invitation (any) – (required)

  • supported-operations.delete_subscription (any) – (required)

  • supported-operations.invite_user (any) – (required)

  • supported-operations.leave_subscription (any) – (required)

  • supported-operations.modify_subscription (any) – (required)

  • supported-operations.renew_license (any) –

  • supported-operations.view_api_jwt_tokens (any) –

  • supported-operations.view_members (any) – (required)

  • type (string) – This can be set to ‘trial’ in order to create a trial subscription. It is only legal to set this to true if the ‘create_trial_subscription’-operation (from the ‘supported-operations’ from /api/profile) is enabled and all the various ‘size’ and ‘level’ settings on the subscription is at their minimum values. (required)

  • url (string) – An URL that points to a web-page that is related to the subscription somehow. This url just for human consumption, and would typically be used to point to the home-page of a project, or a wiki-page that describes what the sesam-installation does.

  • was_created_from_a_precreated_subscription (boolean) – Specified if this subscription was create by assigning a precreated subscription.

GET /api/subscriptions/{subscription_id}/api_json_web_tokens

Returns a list of the api JWT tokens for this subscription

Parameters

  • subscription_id (string) – The subscription id

Status Codes
Response JSON Object

  • [].audit.created_by.email (string) –

  • [].audit.created_by.name (string) –

  • [].audit.created_by.picture (string) –

  • [].audit.created_by.user_id (string) –

  • [].audit.created_ts (string) –

  • [].audit.last_modified_by.email (string) –

  • [].audit.last_modified_by.name (string) –

  • [].audit.last_modified_by.picture (string) –

  • [].audit.last_modified_by.user_id (string) –

  • [].audit.last_modified_ts (string) –

  • [].client_id (string) – Optional. The ‘client_id’ (if any) associated with this JWT. This is only present for tokens where the refresh_interval has been set.

  • [].client_secret (string) – Optional. The ‘client_secret’ (if any) associated with this JWT. For security-reasons this is only returned when the JWT is created. This is only present for tokens where the refresh_interval has been set.

  • [].description (string) – A user-assigned description of this token. (required)

  • [].id (string) – The internal id of the token (required)

  • [].jwt_string (string) – The actual signed JWT. For security-reasons this is only returned when the JWT is created.

  • [].name (string) – A user-assigned name for this token. (required)

  • [].payload.api_token_id (string) – The id of this JWT api token. We need a copy of the id in the payload, since the sesam-node needs to be able to retrieve it in order to check if the token has been invalidated. (required)

  • [].payload.exp (number) – Standard “expiration time” field. This is measured in the number of seconds since the Epoch. Note that if the ‘refresh_interval’ parameter is set, this is not the “exp” value that will actually be in the jwt_string; instead the value will be “current_time + refresh_interval” (required)

  • [].payload.iat (number) – Standard “issued at” field. This is measured in the number of seconds since the Epoch. (required)

  • [].payload.principals (object) – This is a mapping from subscriptionid to the list of principals for that subscription. The reason we have a mapping is that our JWTs can contain potentially contain permissions for more than one subscription. In this case there will alwasy be exactly one subscription_id in this mapping (i.e. for the subscription that this api jwt belongs to). (required)

  • [].payload.user_id (string) – (required)

  • [].payload.user_principal (string) – This is the principal that normally represents the user itself. This is always set to ‘group:Everyone’ for api JWTs.

  • [].payload.user_profile.email (string) –

  • [].payload.user_profile.name (string) –

  • [].payload.user_profile.picture (string) – An URL pointing to an (avatar-)picture of the user

  • [].refresh_interval (number) – Optional. Specifies the interval (in seconds) at which the token must be refreshed.

  • [].supported-operations.delete_api_jwt_token (any) – (required)

POST /api/subscriptions/{subscription_id}/api_json_web_tokens

Creates a new API JWT for the specified subscription. These are json web tokens that are intended for use by things like scripts and cron-jobs, where you need a long-lasting JWT with a specific set of roles.

Parameters

  • subscription_id (string) – The subscription id

Request JSON Object

  • description (string) – A user-assigned description of this token. This is optional and is only used in the GUI.

  • exp (number) – The expiration-date to set on the new JWT. This is measured in number of seconds since the Epoch. (required)

  • name (string) – A user-assigned name for this token. This is optional and is only used in the GUI.

  • principals[] (string) –

  • refresh_interval (number) – Optional. If this is specified, the resulting JWT must be refreshed at the specified rate. In this case the ‘exp’ property describes the last time the JWT can be refreshed.

Status Codes

  • 200 OK – The new SubscriptionJWT

Response JSON Object

  • audit.created_by.email (string) –

  • audit.created_by.name (string) –

  • audit.created_by.picture (string) –

  • audit.created_by.user_id (string) –

  • audit.created_ts (string) –

  • audit.last_modified_by.email (string) –

  • audit.last_modified_by.name (string) –

  • audit.last_modified_by.picture (string) –

  • audit.last_modified_by.user_id (string) –

  • audit.last_modified_ts (string) –

  • client_id (string) – Optional. The ‘client_id’ (if any) associated with this JWT. This is only present for tokens where the refresh_interval has been set.

  • client_secret (string) – Optional. The ‘client_secret’ (if any) associated with this JWT. For security-reasons this is only returned when the JWT is created. This is only present for tokens where the refresh_interval has been set.

  • description (string) – A user-assigned description of this token. (required)

  • id (string) – The internal id of the token (required)

  • jwt_string (string) – The actual signed JWT. For security-reasons this is only returned when the JWT is created.

  • name (string) – A user-assigned name for this token. (required)

  • payload.api_token_id (string) – The id of this JWT api token. We need a copy of the id in the payload, since the sesam-node needs to be able to retrieve it in order to check if the token has been invalidated. (required)

  • payload.exp (number) – Standard “expiration time” field. This is measured in the number of seconds since the Epoch. Note that if the ‘refresh_interval’ parameter is set, this is not the “exp” value that will actually be in the jwt_string; instead the value will be “current_time + refresh_interval” (required)

  • payload.iat (number) – Standard “issued at” field. This is measured in the number of seconds since the Epoch. (required)

  • payload.principals (object) – This is a mapping from subscriptionid to the list of principals for that subscription. The reason we have a mapping is that our JWTs can contain potentially contain permissions for more than one subscription. In this case there will alwasy be exactly one subscription_id in this mapping (i.e. for the subscription that this api jwt belongs to). (required)

  • payload.user_id (string) – (required)

  • payload.user_principal (string) – This is the principal that normally represents the user itself. This is always set to ‘group:Everyone’ for api JWTs.

  • payload.user_profile.email (string) –

  • payload.user_profile.name (string) –

  • payload.user_profile.picture (string) – An URL pointing to an (avatar-)picture of the user

  • refresh_interval (number) – Optional. Specifies the interval (in seconds) at which the token must be refreshed.

  • supported-operations.delete_api_jwt_token (any) – (required)

DELETE /api/subscriptions/{subscription_id}/api_json_web_tokens/{api_json_web_token_id}

Deletes the specified api JWT token

Parameters

  • subscription_id (string) – The subscription id

  • api_json_web_token_id (string) – The api jwt id

Status Codes
GET /api/subscriptions/{subscription_id}/available-roles/{role_id}

Returns information about the specified role in the specified subscription.

Parameters

  • subscription_id (string) – The subscription id

  • role_id (string) – The role id

Status Codes
Response JSON Object

  • child-roles[] (string) –

  • description (string) – A longer description of the role. The gui can use this for tooltips.

  • id (string) – The internal id of the role.

  • name (string) – A human readable name for the role. This is what the gui displays.

DELETE /api/subscriptions/{subscription_id}/available-roles/{role_id}

Deletes the specified role in the specified subscription.

Parameters

  • subscription_id (string) – The subscription id

  • role_id (string) – The role id

Status Codes
Response JSON Object

  • child-roles[] (string) –

  • description (string) – A longer description of the role. The gui can use this for tooltips.

  • id (string) – The internal id of the role.

  • name (string) – A human readable name for the role. This is what the gui displays.

PUT /api/subscriptions/{subscription_id}/available-roles/{role_id}

Updates the specified role in the specified subscription.

Parameters

  • subscription_id (string) – The subscription id

  • role_id (string) – The role id

Request JSON Object

  • child-roles[] (string) –

  • description (string) – A longer description of the role. The gui can use this for tooltips.

  • id (string) – The internal id of the role.

  • name (string) – A human readable name for the role. This is what the gui displays.

Status Codes
Response JSON Object

  • child-roles[] (string) –

  • description (string) – A longer description of the role. The gui can use this for tooltips.

  • id (string) – The internal id of the role.

  • name (string) – A human readable name for the role. This is what the gui displays.

GET /api/subscriptions/{subscription_id}/members

returns a list of the members in the subscription

Parameters

  • subscription_id (string) – The subscription id

Query Parameters

  • limit (integer) – Specifies the maximum number of members to return. If this is not specified, all available members are returned.

  • start (integer) – The index of the first member to return. This defaults to 0 (zero), which means to start at the beginning of the list of members. The ‘start’ parameter can be used in conjunction with the ‘limit’ parameter to implement pagination.

Status Codes
Response JSON Object

  • []._updated (any) – This is a version-value that is used to implement optimistic locking on the server. The client can include this value when doing a PUT to the server; the server will then check that the current _updated value matches the value sent by the client. Note that this value can be of any type, so the client shouldn’t make any assumptions about it.

  • [].audit.invited_by.email (string) –

  • [].audit.invited_by.name (string) –

  • [].audit.invited_by.picture (string) –

  • [].audit.invited_by.user_id (string) –

  • [].audit.invited_ts (string) –

  • [].roles[] (string) –

  • [].sesam_support_info.exp (string) – The “expiration” timestamp of this membership. (required)

  • [].sesam_support_info.iat (string) – The “issued at” timestamp of this membership.

  • [].sesam_support_info.reason (any) – The reason the sesam-employee stated for joining the subscription.

  • [].user.email (string) –

  • [].user.name (string) –

  • [].user.picture (string) –

  • [].user.user_id (string) –

POST /api/subscriptions/{subscription_id}/members

Invites a user to the subscription

Parameters

  • subscription_id (string) – The subscription id

Request JSON Object

  • email (string) – The email-address of the user to invite. This email address will also be the user’s unique id.

  • roles[] (string) –

Status Codes
Response JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. The client can include this value when doing a PUT to the server; the server will then check that the current _updated value matches the value sent by the client. Note that this value can be of any type, so the client shouldn’t make any assumptions about it.

  • audit.invited_by.email (string) –

  • audit.invited_by.name (string) –

  • audit.invited_by.picture (string) –

  • audit.invited_by.user_id (string) –

  • audit.invited_ts (string) –

  • roles[] (string) –

  • sesam_support_info.exp (string) – The “expiration” timestamp of this membership. (required)

  • sesam_support_info.iat (string) – The “issued at” timestamp of this membership.

  • sesam_support_info.reason (any) – The reason the sesam-employee stated for joining the subscription.

  • user.email (string) –

  • user.name (string) –

  • user.picture (string) –

  • user.user_id (string) –

GET /api/subscriptions/{subscription_id}/members/{user_id}

returns information about the roles the specified user has in the subscription

Parameters

  • subscription_id (string) – The subscription id

  • user_id (string) – The user id

Status Codes
Response JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. The client can include this value when doing a PUT to the server; the server will then check that the current _updated value matches the value sent by the client. Note that this value can be of any type, so the client shouldn’t make any assumptions about it.

  • audit.invited_by.email (string) –

  • audit.invited_by.name (string) –

  • audit.invited_by.picture (string) –

  • audit.invited_by.user_id (string) –

  • audit.invited_ts (string) –

  • roles[] (string) –

  • sesam_support_info.exp (string) – The “expiration” timestamp of this membership. (required)

  • sesam_support_info.iat (string) – The “issued at” timestamp of this membership.

  • sesam_support_info.reason (any) – The reason the sesam-employee stated for joining the subscription.

  • user.email (string) –

  • user.name (string) –

  • user.picture (string) –

  • user.user_id (string) –

PUT /api/subscriptions/{subscription_id}/members/{user_id}

updates the roles the specified user has in the subscription

Parameters

  • subscription_id (string) – The subscription id

  • user_id (string) – The user id

Request JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. The value should be the same as the value specified by the server in the SubscriptionMemberInfo object. Note that this value can be of any type, so the client shouldn’t make any assumptions about it.

  • roles[] (string) –

Status Codes
Response JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. The client can include this value when doing a PUT to the server; the server will then check that the current _updated value matches the value sent by the client. Note that this value can be of any type, so the client shouldn’t make any assumptions about it.

  • audit.invited_by.email (string) –

  • audit.invited_by.name (string) –

  • audit.invited_by.picture (string) –

  • audit.invited_by.user_id (string) –

  • audit.invited_ts (string) –

  • roles[] (string) –

  • sesam_support_info.exp (string) – The “expiration” timestamp of this membership. (required)

  • sesam_support_info.iat (string) – The “issued at” timestamp of this membership.

  • sesam_support_info.reason (any) – The reason the sesam-employee stated for joining the subscription.

  • user.email (string) –

  • user.name (string) –

  • user.picture (string) –

  • user.user_id (string) –

GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/available-notification-ruletypes

Returns a list of the available notification rule types on the specified pipe. The idea is that the client can use this list to dynamically generate a gui that lets the user add and edit notification rules.

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

Status Codes
Response JSON Object

  • [].description (string) – A description of the rule-type (required)

  • [].name (string) – The human-readable name of the rule-type (required)

  • [].schema (object) – A JSON Schema that describes which extra parameters (if any) this rule requires. When the portal backend receives a request on the ‘/api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules’ endpoint, this schema is used to validate the request’s json payload. (required)

  • [].type (string) – The type of the notification_rule (required)

PUT /api/admin/config/validation_hack_for_NewPipeNotificationRuleInfo

This is a dummy endpoint that is used to register the NewPipeNotificationRuleInfo definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Request JSON Object

  • description (string) – A user-defined description of the notification_rule. This can be used for instance to explain what steps should be taken if the notification_rule is triggered.

  • extra_rule_info (object) – Any extra rule-specific information. For some rules the rule “type” is enough information, but some rules requires additional information (for instance min- and max- values for some metric). This information is specified by adding attributes to this object as needed.

  • id (string) – The internal id of the notification_rule. It this is not assigned by the user, it will be set to a unique value by the server.

  • name (string) – A short user-defined name for the notification_rule.

  • recipients[].id (any) – The id of this recipient. This can be a role-id (in which case every user with this roleid gets notified), a user-id, or a plain email address. The ‘type’ property specifies how the ‘id’ should be interpreted. (required)

  • recipients[].methods[] (string) –

  • recipients[].type (string) – Specifies what the ‘id’ property refers to.

  • type (string) – The type of the notification_rule (required)

Status Codes
GET /api/subscriptions/{subscription_id}/notification-rules

Returns a list of the notification rules for all pipes in the subscription

Parameters

  • subscription_id (string) – The subscription id

Status Codes
Response JSON Object

  • [].description (string) – A user-defined description of the notification_rule. This can be used for instance to explain what steps should be taken if the notification_rule is triggered.

  • [].extra_rule_info (object) – Any extra rule-specific information. For some rules the rule “type” is enough information, but some rules requires additional information (for instance min- and max- values for some metric). This information is specified by adding attributes to this object as needed.

  • [].id (string) – (required)

  • [].name (string) – A short user-defined name for the notification_rule.

  • [].pipe_id (string) – This property is only present if the notification-rule belongs to one specific pipe (as opposed to belonging to the subscription itself).

  • [].recipients[].id (any) – The id of this recipient. This can be a role-id (in which case every user with this roleid gets notified), a user-id, or a plain email address. The ‘type’ property specifies how the ‘id’ should be interpreted. (required)

  • [].recipients[].methods[] (string) –

  • [].recipients[].type (string) – Specifies what the ‘id’ property refers to.

  • [].type (string) – The type of the notification_rule (required)

POST /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules

Add a new notification rule entry on the specified pipe

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

Request JSON Object

  • description (string) – A user-defined description of the notification_rule. This can be used for instance to explain what steps should be taken if the notification_rule is triggered.

  • extra_rule_info (object) – Any extra rule-specific information. For some rules the rule “type” is enough information, but some rules requires additional information (for instance min- and max- values for some metric). This information is specified by adding attributes to this object as needed.

  • id (string) – The internal id of the notification_rule. It this is not assigned by the user, it will be set to a unique value by the server.

  • name (string) – A short user-defined name for the notification_rule.

  • recipients[].id (any) – The id of this recipient. This can be a role-id (in which case every user with this roleid gets notified), a user-id, or a plain email address. The ‘type’ property specifies how the ‘id’ should be interpreted. (required)

  • recipients[].methods[] (string) –

  • recipients[].type (string) – Specifies what the ‘id’ property refers to.

  • type (string) – The type of the notification_rule (required)

Status Codes
Response JSON Object

  • description (string) – A user-defined description of the notification_rule. This can be used for instance to explain what steps should be taken if the notification_rule is triggered.

  • extra_rule_info (object) – Any extra rule-specific information. For some rules the rule “type” is enough information, but some rules requires additional information (for instance min- and max- values for some metric). This information is specified by adding attributes to this object as needed.

  • id (string) – (required)

  • name (string) – A short user-defined name for the notification_rule.

  • pipe_id (string) – This property is only present if the notification-rule belongs to one specific pipe (as opposed to belonging to the subscription itself).

  • recipients[].id (any) – The id of this recipient. This can be a role-id (in which case every user with this roleid gets notified), a user-id, or a plain email address. The ‘type’ property specifies how the ‘id’ should be interpreted. (required)

  • recipients[].methods[] (string) –

  • recipients[].type (string) – Specifies what the ‘id’ property refers to.

  • type (string) – The type of the notification_rule (required)

GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules

Returns a list of the notification rules on the specified pipe

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

Status Codes
Response JSON Object

  • [].description (string) – A user-defined description of the notification_rule. This can be used for instance to explain what steps should be taken if the notification_rule is triggered.

  • [].extra_rule_info (object) – Any extra rule-specific information. For some rules the rule “type” is enough information, but some rules requires additional information (for instance min- and max- values for some metric). This information is specified by adding attributes to this object as needed.

  • [].id (string) – (required)

  • [].name (string) – A short user-defined name for the notification_rule.

  • [].pipe_id (string) – This property is only present if the notification-rule belongs to one specific pipe (as opposed to belonging to the subscription itself).

  • [].recipients[].id (any) – The id of this recipient. This can be a role-id (in which case every user with this roleid gets notified), a user-id, or a plain email address. The ‘type’ property specifies how the ‘id’ should be interpreted. (required)

  • [].recipients[].methods[] (string) –

  • [].recipients[].type (string) – Specifies what the ‘id’ property refers to.

  • [].type (string) – The type of the notification_rule (required)

PUT /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}

Updates the specified notification rule entry.

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

  • notification_rule_id (string) – The notification_rule id

Request JSON Object

  • description (string) – A user-defined description of the notification_rule. This can be used for instance to explain what steps should be taken if the notification_rule is triggered.

  • extra_rule_info (object) – Any extra rule-specific information. For some rules the rule “type” is enough information, but some rules requires additional information (for instance min- and max- values for some metric). This information is specified by adding attributes to this object as needed.

  • name (string) – A short user-defined name for the notification_rule.

  • recipients[].id (any) – The id of this recipient. This can be a role-id (in which case every user with this roleid gets notified), a user-id, or a plain email address. The ‘type’ property specifies how the ‘id’ should be interpreted. (required)

  • recipients[].methods[] (string) –

  • recipients[].type (string) – Specifies what the ‘id’ property refers to.

Status Codes
Response JSON Object

  • description (string) – A user-defined description of the notification_rule. This can be used for instance to explain what steps should be taken if the notification_rule is triggered.

  • extra_rule_info (object) – Any extra rule-specific information. For some rules the rule “type” is enough information, but some rules requires additional information (for instance min- and max- values for some metric). This information is specified by adding attributes to this object as needed.

  • id (string) – (required)

  • name (string) – A short user-defined name for the notification_rule.

  • pipe_id (string) – This property is only present if the notification-rule belongs to one specific pipe (as opposed to belonging to the subscription itself).

  • recipients[].id (any) – The id of this recipient. This can be a role-id (in which case every user with this roleid gets notified), a user-id, or a plain email address. The ‘type’ property specifies how the ‘id’ should be interpreted. (required)

  • recipients[].methods[] (string) –

  • recipients[].type (string) – Specifies what the ‘id’ property refers to.

  • type (string) – The type of the notification_rule (required)

GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}

Gets the specified notification rule entry.

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

  • notification_rule_id (string) – The notification_rule id

Status Codes
Response JSON Object

  • description (string) – A user-defined description of the notification_rule. This can be used for instance to explain what steps should be taken if the notification_rule is triggered.

  • extra_rule_info (object) – Any extra rule-specific information. For some rules the rule “type” is enough information, but some rules requires additional information (for instance min- and max- values for some metric). This information is specified by adding attributes to this object as needed.

  • id (string) – (required)

  • name (string) – A short user-defined name for the notification_rule.

  • pipe_id (string) – This property is only present if the notification-rule belongs to one specific pipe (as opposed to belonging to the subscription itself).

  • recipients[].id (any) – The id of this recipient. This can be a role-id (in which case every user with this roleid gets notified), a user-id, or a plain email address. The ‘type’ property specifies how the ‘id’ should be interpreted. (required)

  • recipients[].methods[] (string) –

  • recipients[].type (string) – Specifies what the ‘id’ property refers to.

  • type (string) – The type of the notification_rule (required)

DELETE /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}

Deletes the specified notification rule entry.

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

  • notification_rule_id (string) – The notification_rule id

Status Codes
GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}/notifications

Returns the notifications that has been triggered by the specified notification rule.

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

  • notification_rule_id (string) – The notification_rule id

Query Parameters

  • limit (integer) – Specifies the maximum number of notifications to return. If this is not specified, a reasonable default limit will still be used.

  • since (string) – This can be set to a ISO 8601 datetime string to only return notifications that are more recent than the specified datetime.

  • include_dismissed (boolean) – Specified if dismissed notifications should be included in the results.

Status Codes
Response JSON Object

  • [].alerts_will_be_visible_for_the_current_user (boolean) – This is true if this notification should generate an alert for the user. This can be false if the user is looking at one specific notification-rule in the GUI; in that case we want do display all notifications, including the ones that won’t trigger alerts for the current user. (required)

  • [].event_count (integer) – The number of instances of the notification-rule triggering that this notification represents. To prevent a rough notification-rule from creating thousands of identical notifications, the number of notifications that can be created within a certain time-span is limited. But we still need to keep track of the total number of times the notification-rule has triggered, so we increment this value as needed. (required)

  • [].event_timestamp (string) – (required)

  • [].extra_notification_info (object) – This is a json-object with additional notification-ruletype specific information about the notification.

  • [].is_ongoing (boolean) – This is true if the notification is still “ongoing”, meaning that the condition that caused the notification to trigger hasn’t since been resolved. (required)

  • [].last_event_timestamp (string) – The timestamp of the last notification-rule triggering that this notification represents. See the also the ‘event_count’ property. (required)

  • [].msg (string) – A human-readable message describing the notification. (required)

  • [].notification_id (integer) – An integer that uniquely identifies this notification. (required)

  • [].notification_rule_id (string) – The id of the notification rule that triggered this notification. (required)

  • [].notification_rule_name (string) – The name of the notification rule that triggered this notification. (required)

  • [].notification_rule_type (string) – The type of the notification rule that triggered this notification. (required)

  • [].pipe_id (string) – The id of the pipe that this notification belongs to (if any). If the notification doesn’t belong to a pipe, this property will not be present.

  • [].subscription_id (string) – The id of the subscription that this notification belongs to (if any). If the notification doesn’t belong to a subscription, this property will not be present.

GET /api/notifications

Returns the notifications that should be displayed in the “Alerts”-list for this user.

Query Parameters

  • limit (integer) – Specifies the maximum number of notifications to return. If this is not specified, a reasonable default limit will still be used.

  • since (string) – This can be set to a ISO 8601 datetime string to only return notifications that are more recent than the specified datetime.

  • include_dismissed (boolean) – Specifies if dismissed notifications should be included in the results.

Status Codes
Response JSON Object

  • [].alerts_will_be_visible_for_the_current_user (boolean) – This is true if this notification should generate an alert for the user. This can be false if the user is looking at one specific notification-rule in the GUI; in that case we want do display all notifications, including the ones that won’t trigger alerts for the current user. (required)

  • [].event_count (integer) – The number of instances of the notification-rule triggering that this notification represents. To prevent a rough notification-rule from creating thousands of identical notifications, the number of notifications that can be created within a certain time-span is limited. But we still need to keep track of the total number of times the notification-rule has triggered, so we increment this value as needed. (required)

  • [].event_timestamp (string) – (required)

  • [].extra_notification_info (object) – This is a json-object with additional notification-ruletype specific information about the notification.

  • [].is_ongoing (boolean) – This is true if the notification is still “ongoing”, meaning that the condition that caused the notification to trigger hasn’t since been resolved. (required)

  • [].last_event_timestamp (string) – The timestamp of the last notification-rule triggering that this notification represents. See the also the ‘event_count’ property. (required)

  • [].msg (string) – A human-readable message describing the notification. (required)

  • [].notification_id (integer) – An integer that uniquely identifies this notification. (required)

  • [].notification_rule_id (string) – The id of the notification rule that triggered this notification. (required)

  • [].notification_rule_name (string) – The name of the notification rule that triggered this notification. (required)

  • [].notification_rule_type (string) – The type of the notification rule that triggered this notification. (required)

  • [].pipe_id (string) – The id of the pipe that this notification belongs to (if any). If the notification doesn’t belong to a pipe, this property will not be present.

  • [].subscription_id (string) – The id of the subscription that this notification belongs to (if any). If the notification doesn’t belong to a subscription, this property will not be present.

GET /api/notifications-summary

Returns the status of all subscriptions and pipes with notification-rules that the user have access to. This endpoint implements the Sesam “json-pull” protocol (https://docs.sesam.io/hub/json-pull.html).

Query Parameters

  • limit (integer) – Specifies the maximum number of items to return. If this is not specified, all available items will be returned

  • since (integer) – This is the ‘since’-value in the sesam json-pull protocol (https://docs.sesam.io/hub/json-pull.html)

  • deleted (boolean) – Specifies if deleted entries should be included in the results.

Status Codes
Response JSON Object

  • []._deleted (boolean) – (required)

  • []._id (string) – The id of the pipe that this item represents (required)

  • []._updated (number) – (required)

  • [].confidence (number) – This number specifies how confident the system is that the status is accurate. This is normally 1, which means that the notification machinery is working as normal. If there is an internal problem with the notification machinery itself, the confidence will be between 1 and 0.

  • [].notifications[].alerts_will_be_visible_for_the_current_user (boolean) – This is true if this notification should generate an alert for the user. This can be false if the user is looking at one specific notification-rule in the GUI; in that case we want do display all notifications, including the ones that won’t trigger alerts for the current user. (required)

  • [].notifications[].event_count (integer) – The number of instances of the notification-rule triggering that this notification represents. To prevent a rough notification-rule from creating thousands of identical notifications, the number of notifications that can be created within a certain time-span is limited. But we still need to keep track of the total number of times the notification-rule has triggered, so we increment this value as needed. (required)

  • [].notifications[].event_timestamp (string) – (required)

  • [].notifications[].extra_notification_info (object) – This is a json-object with additional notification-ruletype specific information about the notification.

  • [].notifications[].is_ongoing (boolean) – This is true if the notification is still “ongoing”, meaning that the condition that caused the notification to trigger hasn’t since been resolved. (required)

  • [].notifications[].last_event_timestamp (string) – The timestamp of the last notification-rule triggering that this notification represents. See the also the ‘event_count’ property. (required)

  • [].notifications[].msg (string) – A human-readable message describing the notification. (required)

  • [].notifications[].notification_id (integer) – An integer that uniquely identifies this notification. (required)

  • [].notifications[].notification_rule_id (string) – The id of the notification rule that triggered this notification. (required)

  • [].notifications[].notification_rule_name (string) – The name of the notification rule that triggered this notification. (required)

  • [].notifications[].notification_rule_type (string) – The type of the notification rule that triggered this notification. (required)

  • [].notifications[].pipe_id (string) – The id of the pipe that this notification belongs to (if any). If the notification doesn’t belong to a pipe, this property will not be present.

  • [].notifications[].subscription_id (string) – The id of the subscription that this notification belongs to (if any). If the notification doesn’t belong to a subscription, this property will not be present.

  • [].pipe_id (string) – The id of the pipe that this item represents. This property is optional and is only present if the item represents a pipe.

  • [].status (string) – If status is “ok” no notification-rules have triggered. If status is “failed” if at least one user-defined notification-rule has triggered. This property is not present in items where “_deleted” is true.

  • [].subscription_id (string) – The id of the subscription that this item belongs to (required)

GET /api/monitoring/standard/{subscription_id}/pipes/{pipe_id}

Returns standard monitoring information about the specified pipe

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

Status Codes
GET /api/monitoring/standard/{subscription_id}

Returns standard monitoring information about the specified subscription

Parameters

  • subscription_id (string) – The subscription id

Status Codes
GET /api/monitoring/invoicing/{subscription_id}

Returns invoicing information for the specified subscription

Parameters

  • subscription_id (string) – The subscription id

Status Codes
GET /api/sso

Used for SSO authentication. If the portal detects that a user is in session, it creates a JWT and redirects to a provided URL. If not, it serves a login page to authenticate. Right now, this only works with Zendesk.

Query Parameters

  • return_to (string) – The URL to return to after authentication

Status Codes
GET /api/login_implicit_flow

This is only used when logging in with openid connect providers that only support the “implicit flow” method. In that case the “id_token” is returned as part for the fragment-part of the url (the bit after the “#”-sign), which isn’t sent to the backend. The login_implicit_flow page contains a javascript snippet that extracts the id_token and calls the jwt_login endpoint.

Status Codes
POST /api/jwt_login

This is only used when logging in with openid connect providers that only support the “implicit flow” method.

Status Codes
POST /api/login/{provider_id}

This starts an openid connect authentication prosess. The user will eventually be redirected back to the ‘/login_callback/{provider_id}’ endpoint.

Parameters

  • provider_id (string) – The name of the openid connect authentication provider. This must match a provider that has been configured in the sesamportal.yaml file.

Status Codes

  • 302 Found – A redirect to the authentication provider’s login-page.

GET /api/login_callback/{provider_id}

The user is redirected back here after authenticating with an openid connect authentication provider.

Parameters

  • provider_id (string) – The name of the openid connect authentication provider. This must match a provider that has been configured in the sesamportal.yaml file.

Query Parameters

  • code (string) – A short-lived authorization code from the authentication provider. The DAP backend will use this code to retrieve the user’s information from the authentication provider.

Status Codes

  • 302 Found – Redirect to the sesam portal frontpage

POST /api/login

This is called when the user wants to authenticate with an email-address and a password. If the login is successful, a new http session is created, and the sessionid is returned in a cookie.

Status Codes
GET /api/logout

Logs out the currently logged-in user, and clears the http session data. This is the legacy logout that returns a json object (the same as the /api/profile endpoint). This endpoint is deprected and should be removed once the gui has been updated to use the “/api/logout2” endpoint.

Status Codes
Response JSON Object

  • supported-operations.activate_portal_admin_powers (any) – (required)

  • supported-operations.create_paymentmethod (any) – (required)

  • supported-operations.create_subscription (any) – (required)

  • supported-operations.create_trial_subscription (any) – (required)

  • supported-operations.delete_account (any) – (required)

  • supported-operations.request_email_verification (any) – (required)

  • supported-operations.request_trial_subscription (any) – (required)

  • supported-operations.send_reset_password_email (any) – (required)

  • supported-operations.update_user_profile (any) – (required)

  • userInfo.isLoggedIn (boolean) –

  • userInfo.lastRequestTrial.created_time (string) – The time when the user made the request, as a ISO 8601 formatted string.

  • userInfo.lastRequestTrial.dismissed_from_gui (boolean) – This can be set to true to hide a denied request from the user’s gui.

  • userInfo.lastRequestTrial.responded_time (string) – The time when the request was answered, as a ISO 8601 formatted string.

  • userInfo.lastRequestTrial.response (string) – A text describing the reason behind the result (typically used to explain why the request was denied.

  • userInfo.lastRequestTrial.status (string) – The result of the request.

  • userInfo.lastRequestTrial.user_submitted_information (object) – The information the user submits when requesting information. This information is diplayed to the sesam employee that reviews the “create trial” request. The exact properties that are present is decided by the GUI; both the backend storage and the admin form the sesam employee uses can handle any number and types of properties.

  • userInfo.profile.email (string) –

  • userInfo.profile.email_is_verified (boolean) –

  • userInfo.profile.name (string) –

  • userInfo.profile.nickname (string) –

  • userInfo.profile.picture (string) –

  • userInfo.providerIds[] (string) –

  • userInfo.providerWhitelist[] (string) –

  • userInfo.user_id (string) –

GET /api/logout2

Logs out the currently logged-in user, and clears the http session data.

Status Codes

  • 302 Found – This redirect either to the sesam portal frontpage, or to a url that lets the user log out properly from a third party authentication provider.

POST /api/signup

Signs up a new user

Status Codes
GET /api/available-subscription-settings

service for returning the various choices that exists for the various subscription settings

Status Codes
Response JSON Object

  • products.datahub.size[].label (string) – The label-text to use for this option (required)

  • products.datahub.size[].maximum_store_disk_usage (integer) – The maximum number of bytes that the datahub’s store is allowed to use on disk. (required)

  • products.datahub.size[].size (string) – The size-value of this option (“small”, “medium”, etc). (required)

POST /api/estimate-subscription-price

service for calculating subscription price, based on a description of the select subscription options

Query Parameters

  • expected_data_size (integer) – What is the expected data size of the subscription

Request JSON Object

  • connections[].id (string) – The name “id” is a special case; it represents the default sesam-node connection. When the item’s type is “databrowser”, the id refers to a databrowser in the “databrowser”-list in the “products”-part of the subscription info. (required)

  • connections[].name (string) – The human-redable name of the connection. (required)

  • connections[].type (string) – This specified the type of component this connection points to. (required)

  • connections[].url (string) – (required)

  • description (string) – A short description of the subscription.

  • id (string) –

  • license-expiration-date (string) – If this is specified it should be an ISO-8601 formatted datestring. This is used instead of the default value when setting the expiration date of the subscription license. The specified value cannot be in the past or too far in the future (a 400-response will be returned if the value is invalid).

  • name (string) –

  • network.network-acl[].access (string) – (required)

  • network.network-acl[].address (string) – (required)

  • network.public-access (boolean) –

  • paymentmethod_id (string) – The id of the PaymentMethod that the licence-fee for this subscription should be billed to. This property is only present for subscriptions of the type “paid”.

  • products.databrowser[].custom_fqdn[] (string) –

  • products.databrowser[].id (string) – (required)

  • products.databrowser[].name (string) –

  • products.databrowser[].size (string) –

  • products.databrowser[].type (string) – This is only set when the databrower is being used in a gdpr platform

  • products.datahub.backup (string) –

  • products.datahub.byok (boolean) – Setting this to true enables the “Bring Your Own Keys” feature in Azure. See this page for some background on the BYOK feature: https://docs.microsoft.com/en-us/azure/information-protection/byok-price-restrictions Note that enabling this feature incurs additional costs.

  • products.datahub.developer_mode (boolean) – This is a property that is set in some subscriptions to allow certain APIs such as reset node that is dangerous to enable in a production environment

  • products.datahub.fixed_price_gb (integer) – This property specifies the number of GBs that are set as the threshold for the subscription fixed price payment scheme. If this property exists, subscription is invoiced using fixed price scheme.

  • products.datahub.maximum_store_disk_usage (integer) – This is a read-only property that is set in some special cases where a custom server has been set up by sesam employees. It specifies the maximum size of the data store in bytes.

  • products.datahub.monitoring (string) – This can be set to “standard” to enable monitoring for this subscription (this currently requires some manual work by SESAM employees).

  • products.datahub.size (string) – This property describes the size of the node. As of Sep 2021, small, medium, large and xlarge are legacy sizes. The UI maps small/medium to single and xlarge to multi. (required)

  • products.datahub.version (string) – The docker tag that the user wants the sesam-node container to use. The docker tag that is currently in use is specified in the “provisioning_result”->”datahub”->”tag” property. There will always be a delay between the time the user changes the “version”-property and the time when the “provisioning_result”->”datahub”->”tag” property changes; at the very least the sesam-node needs to be stopped and restarted with the new docker-image.

  • products.gdpr_platform.custom_fqdn[] (string) –

  • products.gdpr_platform.name (string) – An optional, humanreadable name for this gdpr platform.

  • products.gdpr_platform.size (string) – (required)

  • products.microservices.size (string) – (required)

  • products.search (boolean) – This controls whether to activate the search capability

  • products.sla.level (string) – (required)

  • products.vpn.connections[]._id (integer) – This is an internal unique id that is assigned to new vpn-connections by the backend. The GUI will not display this value, but will include it as-is in PUT-requests. (The portal backend uses this value to replace the placeholder “****” for the shared_key property in PUT-requests; it needs a way to uniquely identify connections).

  • products.vpn.connections[].address_spaces[] (string) –

  • products.vpn.connections[].gateway_address (string) –

  • products.vpn.connections[].shared_key (string) – This is the secret shared key that is used to authenticate against the VPN. This property is write-only and will always look like “****” in the api-responses from the backend. If the special value “****” is used in a PUT-request, the value is ignored and the current shared_key value will not be changed. The intention is that the GUI can display and send the shared_key value as-is.

  • products.vpn.dns[] (string) –

  • products.vpn.enable_snat (boolean) –

  • products.vpn.local-range (string) –

  • products.vpn.local-subnet (string) –

  • products.vpn.onsite-ranges[] (string) –

  • products.vpn.public-gateway (string) –

  • products.vpn.sesam_address_spaces[] (string) –

  • products.vpn.sesam_gateway (string) –

  • products.vpn.tier (integer) –

  • products.vpn.type (string) –

  • provisioner_version (string) – This specified the provisioner this subscription will be provisioned with. If this value is “1” or missing, and the service specified is “in-cloud”, the original provisioner is used. If the value is “2”, the new “sesam-provisioner” is used. If the version is “snowflake” the Portal won’t provision this subscription.

  • service (string) – Specifies if the subscription is about in in-cloud or on-premise installation. This doesn’t have bearing on whether the Portal provisions this subscription or not, that is controlled by the provisioner_version property as of IS-10634. All on-premise subscriptions have provisioner_version “snowflake” and some in-cloud ones too.

  • type (string) – This can be set to ‘trial’ in order to create a trial subscription. It is only legal to set this to true if the ‘create_trial_subscription’-operation (from the ‘supported-operations’ from /api/profile) is enabled and all the various ‘size’ and ‘level’ settings on the subscription is at their minimum values.

  • url (string) – An URL that points to a web-page that is related to the subscription somehow. This url just for human consumption, and would typically be used to point to the home-page of a project, or a wiki-page that describes what the sesam-installation does.

Status Codes
Response JSON Object

  • currency (string) – (required)

  • dynamic_items.backup_pr_GB.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.monitoring_pr_pipe_basic.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.monitoring_pr_pipe_enterprise.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.monitoring_pr_pipe_standard.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.search_pr_GB.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.sla_pr_GB.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.storage_pr_GB.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.vpn_pr_GB.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_total (string) – Transit-encoded decimal that specifies the total price for all the dynamic items.

  • expected_total_data_cost (string) – Calculated total monthly cost of data (if the expected data size was provided, otherwise not present)

  • fixed_items.datahub.price (string) – Transit-encoded decimal that specifies the price in the currency specified by the ‘currency’ property. (required)

  • fixed_items.datahub.sub_type (string) – The ‘main’ type is given by the property-name used in the PriceEstimate to refer to this PriceEstimateFixedItem. The ‘sub_type’ specifies a more fine-grained type. (required)

  • fixed_items.microservices.price (string) – Transit-encoded decimal that specifies the price in the currency specified by the ‘currency’ property. (required)

  • fixed_items.microservices.sub_type (string) – The ‘main’ type is given by the property-name used in the PriceEstimate to refer to this PriceEstimateFixedItem. The ‘sub_type’ specifies a more fine-grained type. (required)

  • fixed_items.search.price (string) – Transit-encoded decimal that specifies the price in the currency specified by the ‘currency’ property. (required)

  • fixed_items.search.sub_type (string) – The ‘main’ type is given by the property-name used in the PriceEstimate to refer to this PriceEstimateFixedItem. The ‘sub_type’ specifies a more fine-grained type. (required)

  • fixed_items.sla.price (string) – Transit-encoded decimal that specifies the price in the currency specified by the ‘currency’ property. (required)

  • fixed_items.sla.sub_type (string) – The ‘main’ type is given by the property-name used in the PriceEstimate to refer to this PriceEstimateFixedItem. The ‘sub_type’ specifies a more fine-grained type. (required)

  • fixed_items.vpn.price (string) – Transit-encoded decimal that specifies the price in the currency specified by the ‘currency’ property. (required)

  • fixed_items.vpn.sub_type (string) – The ‘main’ type is given by the property-name used in the PriceEstimate to refer to this PriceEstimateFixedItem. The ‘sub_type’ specifies a more fine-grained type. (required)

  • fixed_total (string) – Transit-encoded decimal that specifies the total price for all the fixed items. (required)

POST /api/subscriptions/{subscription_id}/estimate-subscription-price

service for calculating a new subscription price, based on a description of the select subscription options

Parameters

  • subscription_id (string) – The subscription id

Query Parameters

  • expected_data_size (integer) – What is the expected data size of the subscription

Request JSON Object

  • connections[].id (string) – The name “id” is a special case; it represents the default sesam-node connection. When the item’s type is “databrowser”, the id refers to a databrowser in the “databrowser”-list in the “products”-part of the subscription info. (required)

  • connections[].name (string) – The human-redable name of the connection. (required)

  • connections[].type (string) – This specified the type of component this connection points to. (required)

  • connections[].url (string) – (required)

  • description (string) – A short description of the subscription.

  • name (string) –

  • network.network-acl[].access (string) – (required)

  • network.network-acl[].address (string) – (required)

  • network.public-access (boolean) –

  • paymentmethod_id (string) – The id of the PaymentMethod that the licence-fee for this subscription should be billed to. This property is only present for subscriptions of the type “paid”.

  • products.databrowser[].custom_fqdn[] (string) –

  • products.databrowser[].id (string) – (required)

  • products.databrowser[].name (string) –

  • products.databrowser[].size (string) –

  • products.databrowser[].type (string) – This is only set when the databrower is being used in a gdpr platform

  • products.datahub.backup (string) –

  • products.datahub.byok (boolean) – Setting this to true enables the “Bring Your Own Keys” feature in Azure. See this page for some background on the BYOK feature: https://docs.microsoft.com/en-us/azure/information-protection/byok-price-restrictions Note that enabling this feature incurs additional costs.

  • products.datahub.developer_mode (boolean) – This is a property that is set in some subscriptions to allow certain APIs such as reset node that is dangerous to enable in a production environment

  • products.datahub.fixed_price_gb (integer) – This property specifies the number of GBs that are set as the threshold for the subscription fixed price payment scheme. If this property exists, subscription is invoiced using fixed price scheme.

  • products.datahub.maximum_store_disk_usage (integer) – This is a read-only property that is set in some special cases where a custom server has been set up by sesam employees. It specifies the maximum size of the data store in bytes.

  • products.datahub.monitoring (string) – This can be set to “standard” to enable monitoring for this subscription (this currently requires some manual work by SESAM employees).

  • products.datahub.size (string) – This property describes the size of the node. As of Sep 2021, small, medium, large and xlarge are legacy sizes. The UI maps small/medium to single and xlarge to multi. (required)

  • products.datahub.version (string) – The docker tag that the user wants the sesam-node container to use. The docker tag that is currently in use is specified in the “provisioning_result”->”datahub”->”tag” property. There will always be a delay between the time the user changes the “version”-property and the time when the “provisioning_result”->”datahub”->”tag” property changes; at the very least the sesam-node needs to be stopped and restarted with the new docker-image.

  • products.gdpr_platform.custom_fqdn[] (string) –

  • products.gdpr_platform.name (string) – An optional, humanreadable name for this gdpr platform.

  • products.gdpr_platform.size (string) – (required)

  • products.microservices.size (string) – (required)

  • products.search (boolean) – This controls whether to activate the search capability

  • products.sla.level (string) – (required)

  • products.vpn.connections[]._id (integer) – This is an internal unique id that is assigned to new vpn-connections by the backend. The GUI will not display this value, but will include it as-is in PUT-requests. (The portal backend uses this value to replace the placeholder “****” for the shared_key property in PUT-requests; it needs a way to uniquely identify connections).

  • products.vpn.connections[].address_spaces[] (string) –

  • products.vpn.connections[].gateway_address (string) –

  • products.vpn.connections[].shared_key (string) – This is the secret shared key that is used to authenticate against the VPN. This property is write-only and will always look like “****” in the api-responses from the backend. If the special value “****” is used in a PUT-request, the value is ignored and the current shared_key value will not be changed. The intention is that the GUI can display and send the shared_key value as-is.

  • products.vpn.dns[] (string) –

  • products.vpn.enable_snat (boolean) –

  • products.vpn.local-range (string) –

  • products.vpn.local-subnet (string) –

  • products.vpn.onsite-ranges[] (string) –

  • products.vpn.public-gateway (string) –

  • products.vpn.sesam_address_spaces[] (string) –

  • products.vpn.sesam_gateway (string) –

  • products.vpn.tier (integer) –

  • products.vpn.type (string) –

  • url (string) – An URL that points to a web-page that is related to the subscription somehow. This url just for human consumption, and would typically be used to point to the home-page of a project, or a wiki-page that describes what the sesam-installation does.

Status Codes
Response JSON Object

  • currency (string) – (required)

  • dynamic_items.backup_pr_GB.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.monitoring_pr_pipe_basic.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.monitoring_pr_pipe_enterprise.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.monitoring_pr_pipe_standard.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.search_pr_GB.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.sla_pr_GB.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.storage_pr_GB.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_items.vpn_pr_GB.price (string) – Transit-encoded decimal that specifies the price of one unit of this item in the currency specified by the ‘currency’ property. (required)

  • dynamic_total (string) – Transit-encoded decimal that specifies the total price for all the dynamic items.

  • expected_total_data_cost (string) – Calculated total monthly cost of data (if the expected data size was provided, otherwise not present)

  • fixed_items.datahub.price (string) – Transit-encoded decimal that specifies the price in the currency specified by the ‘currency’ property. (required)

  • fixed_items.datahub.sub_type (string) – The ‘main’ type is given by the property-name used in the PriceEstimate to refer to this PriceEstimateFixedItem. The ‘sub_type’ specifies a more fine-grained type. (required)

  • fixed_items.microservices.price (string) – Transit-encoded decimal that specifies the price in the currency specified by the ‘currency’ property. (required)

  • fixed_items.microservices.sub_type (string) – The ‘main’ type is given by the property-name used in the PriceEstimate to refer to this PriceEstimateFixedItem. The ‘sub_type’ specifies a more fine-grained type. (required)

  • fixed_items.search.price (string) – Transit-encoded decimal that specifies the price in the currency specified by the ‘currency’ property. (required)

  • fixed_items.search.sub_type (string) – The ‘main’ type is given by the property-name used in the PriceEstimate to refer to this PriceEstimateFixedItem. The ‘sub_type’ specifies a more fine-grained type. (required)

  • fixed_items.sla.price (string) – Transit-encoded decimal that specifies the price in the currency specified by the ‘currency’ property. (required)

  • fixed_items.sla.sub_type (string) – The ‘main’ type is given by the property-name used in the PriceEstimate to refer to this PriceEstimateFixedItem. The ‘sub_type’ specifies a more fine-grained type. (required)

  • fixed_items.vpn.price (string) – Transit-encoded decimal that specifies the price in the currency specified by the ‘currency’ property. (required)

  • fixed_items.vpn.sub_type (string) – The ‘main’ type is given by the property-name used in the PriceEstimate to refer to this PriceEstimateFixedItem. The ‘sub_type’ specifies a more fine-grained type. (required)

  • fixed_total (string) – Transit-encoded decimal that specifies the total price for all the fixed items. (required)

POST /api/is-available-subscription-name

This service checks that the specified subscription name is unique for specified “owner” and that is a valid name.

Status Codes
Response JSON Object

  • is-available (boolean) – (required)

POST /api/request_trial

This is called when a user wants to request a trial subscription.

Status Codes
POST /api/cancel_request_trial

This is called when a user wants to cancel a previously made ‘create trial’ request.

Status Codes
POST /api/dismiss_denied_request_trial

This is called when a user wants to dismiss a denied ‘create trial’ request (so that the request doens’t show up in the user’s gui any longer).

Status Codes
PUT /api/password

Changes the password of the user. This is called when a user is logged in, but wants to change their password.

Status Codes
Response JSON Object

  • success (boolean) – (required)

POST /api/forgot-password

Sends a mail to the specified emailaddress with a one-time link that lets the user change the password. The link leads to the normal gui with a url parameter that contains the “change-password” one-time token.

Status Codes
Response JSON Object

  • success (boolean) – (required)

POST /api/reset-password

changes the user’s password. This is part of the “forgotten password” flow.

Status Codes
Response JSON Object

  • success (boolean) – (required)

POST /api/verify-emailaddress

Verifies the user’s email address. This is part of the “verify emailaddress” flow.

Status Codes

  • 200 OK – OK, address has been verified

  • 400 Bad Request – Token might be invalid, already used or expired

POST /api/request-email-verification

Asks the portal to send a new ‘Verify emailaddress’ email.

Status Codes

  • 200 OK – OK, a new email has been sent

  • 409 Conflict – The current user already has a pending ‘verify emailaddress email’, so no new email can be sent at this time.

GET /api/payment/stripe_publishable_api_key

Returns the Stripe publishable api key.

Status Codes
POST /api/payment/stripe_coupon

Returns a coupon if it exists

Request JSON Object

  • code (string) – The coupon code

Status Codes
GET /api/sesam_status

Proxy for querying the sesam statuspage API

Status Codes
POST /api/payment/subscription

Creates a new customer and subscription in Stripe and creates a PaymentMethod in the Sesam portal. Also creates a new gdpr subscription in the Sesam Portal (using the new paymentmethod).

Request JSON Object

  • companyAddress (string) – The address of the company

  • companyCity (string) – The city the company resides in

  • companyCountry (string) – The country the company resides in

  • companyName (string) – The name of the company

  • companyZipCode (string) – The zip code of the companys address

  • couponCode (string) – Optional coupon code

  • email (string) – The email that the customer should be linked to

  • phoneNumber (string) – The phone number of the customer

  • token (object) – The token object returned from Stripe

  • vat (string) – The VAT of the company

Status Codes
GET /api/paymentmethods

Returns the paymentmethods that this user owns.

Status Codes
Response JSON Object

  • []._updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • [].audit.created_by.email (string) –

  • [].audit.created_by.name (string) –

  • [].audit.created_by.picture (string) –

  • [].audit.created_by.user_id (string) –

  • [].audit.created_ts (string) –

  • [].audit.last_modified_by.email (string) –

  • [].audit.last_modified_by.name (string) –

  • [].audit.last_modified_by.picture (string) –

  • [].audit.last_modified_by.user_id (string) –

  • [].audit.last_modified_ts (string) –

  • [].billing_info (object) – An json-structure that describes the billing info for the payment method. The client is currently free to store whatever it wants here (but it should be in reasonably structure; we will probably add some validation here later, once we have figured out which fields we need) (required)

  • [].description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use. (required)

  • [].id (string) – The internal id of this paymentmethod. (required)

  • [].is_verified (boolean) – This is set to true when a Portal administrator (i.e a SESAM employee) has manually examined the payment information and checked that it is legitimate. Only portal administrators are allowed to change the value of this property. (required)

  • [].name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use. (required)

  • [].owner.email (string) – The email of the owner (required)

  • [].owner.name (string) – The name of the owner (required)

  • [].owner.picture (string) –

  • [].owner.user_id (string) – The id of the owner (required)

  • [].subscriptions[].id (string) – The subscription id (required)

  • [].subscriptions[].name (string) – The name of the the subscription (required)

  • [].supported-operations.delete_paymentmethod (any) – (required)

  • [].supported-operations.modify_billing_info (any) – (required)

  • [].supported-operations.modify_name_and_description (any) – (required)

  • [].type (string) – The type of this paymentmethod. (required)

POST /api/paymentmethods

Creates a new paymentmethod

Request JSON Object

  • billing_info (object) – An json-structure that describes the billing info for the payment method. The client is currently free to store whatever it wants here (but it should be in reasonably structure; we will probably add some validation here later, once we have figured out which fields we need)

  • card_token (string) – This is set for PaymentMethods that represents a Stripe credit card. This attribute is never sent to the client; it is only sent from the client to the server when the paymentmethod is created.

  • description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use.

  • name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use.

  • type (string) – The type of this paymentmethod.

Status Codes
Response JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • audit.created_by.email (string) –

  • audit.created_by.name (string) –

  • audit.created_by.picture (string) –

  • audit.created_by.user_id (string) –

  • audit.created_ts (string) –

  • audit.last_modified_by.email (string) –

  • audit.last_modified_by.name (string) –

  • audit.last_modified_by.picture (string) –

  • audit.last_modified_by.user_id (string) –

  • audit.last_modified_ts (string) –

  • billing_info (object) – An json-structure that describes the billing info for the payment method. The client is currently free to store whatever it wants here (but it should be in reasonably structure; we will probably add some validation here later, once we have figured out which fields we need) (required)

  • description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use. (required)

  • id (string) – The internal id of this paymentmethod. (required)

  • is_verified (boolean) – This is set to true when a Portal administrator (i.e a SESAM employee) has manually examined the payment information and checked that it is legitimate. Only portal administrators are allowed to change the value of this property. (required)

  • name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use. (required)

  • owner.email (string) – The email of the owner (required)

  • owner.name (string) – The name of the owner (required)

  • owner.picture (string) –

  • owner.user_id (string) – The id of the owner (required)

  • subscriptions[].id (string) – The subscription id (required)

  • subscriptions[].name (string) – The name of the the subscription (required)

  • supported-operations.delete_paymentmethod (any) – (required)

  • supported-operations.modify_billing_info (any) – (required)

  • supported-operations.modify_name_and_description (any) – (required)

  • type (string) – The type of this paymentmethod. (required)

GET /api/paymentmethods/{paymentmethod_id}

Returns information about the specified paymentmethod

Parameters

  • paymentmethod_id (string) – The paymentmethod id

Status Codes
Response JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • audit.created_by.email (string) –

  • audit.created_by.name (string) –

  • audit.created_by.picture (string) –

  • audit.created_by.user_id (string) –

  • audit.created_ts (string) –

  • audit.last_modified_by.email (string) –

  • audit.last_modified_by.name (string) –

  • audit.last_modified_by.picture (string) –

  • audit.last_modified_by.user_id (string) –

  • audit.last_modified_ts (string) –

  • billing_info (object) – An json-structure that describes the billing info for the payment method. The client is currently free to store whatever it wants here (but it should be in reasonably structure; we will probably add some validation here later, once we have figured out which fields we need) (required)

  • description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use. (required)

  • id (string) – The internal id of this paymentmethod. (required)

  • is_verified (boolean) – This is set to true when a Portal administrator (i.e a SESAM employee) has manually examined the payment information and checked that it is legitimate. Only portal administrators are allowed to change the value of this property. (required)

  • name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use. (required)

  • owner.email (string) – The email of the owner (required)

  • owner.name (string) – The name of the owner (required)

  • owner.picture (string) –

  • owner.user_id (string) – The id of the owner (required)

  • subscriptions[].id (string) – The subscription id (required)

  • subscriptions[].name (string) – The name of the the subscription (required)

  • supported-operations.delete_paymentmethod (any) – (required)

  • supported-operations.modify_billing_info (any) – (required)

  • supported-operations.modify_name_and_description (any) – (required)

  • type (string) – The type of this paymentmethod. (required)

DELETE /api/paymentmethods/{paymentmethod_id}

Deletes the specified paymentmethod

Parameters

  • paymentmethod_id (string) – The paymentmethod id

Status Codes
PUT /api/paymentmethods/{paymentmethod_id}

Update the paymentmethod

Parameters

  • paymentmethod_id (string) – The paymentmethod id

Request JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it.

  • billing_info (object) – An json-structure that describes the billing info for the payment method. The client is currently free to store whatever it wants here (but it should be in reasonably structure; we will probably add some validation here later, once we have figured out which fields we need)

  • description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use.

  • name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use.

Status Codes
Response JSON Object

  • _updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • audit.created_by.email (string) –

  • audit.created_by.name (string) –

  • audit.created_by.picture (string) –

  • audit.created_by.user_id (string) –

  • audit.created_ts (string) –

  • audit.last_modified_by.email (string) –

  • audit.last_modified_by.name (string) –

  • audit.last_modified_by.picture (string) –

  • audit.last_modified_by.user_id (string) –

  • audit.last_modified_ts (string) –

  • billing_info (object) – An json-structure that describes the billing info for the payment method. The client is currently free to store whatever it wants here (but it should be in reasonably structure; we will probably add some validation here later, once we have figured out which fields we need) (required)

  • description (string) – A humanreadable description of this paymentmethod. This is for the customers internal use. (required)

  • id (string) – The internal id of this paymentmethod. (required)

  • is_verified (boolean) – This is set to true when a Portal administrator (i.e a SESAM employee) has manually examined the payment information and checked that it is legitimate. Only portal administrators are allowed to change the value of this property. (required)

  • name (string) – A humanreadable name of this paymentmethod. This is for the customers internal use. (required)

  • owner.email (string) – The email of the owner (required)

  • owner.name (string) – The name of the owner (required)

  • owner.picture (string) –

  • owner.user_id (string) – The id of the owner (required)

  • subscriptions[].id (string) – The subscription id (required)

  • subscriptions[].name (string) – The name of the the subscription (required)

  • supported-operations.delete_paymentmethod (any) – (required)

  • supported-operations.modify_billing_info (any) – (required)

  • supported-operations.modify_name_and_description (any) – (required)

  • type (string) – The type of this paymentmethod. (required)

GET /api/admin

Returns a simple htmlpage that lets portal admin perform various operations. This should probably be replaces with a proper fancy page in the normal javascript GUI, but we want the functionality quickly, and only sesam employees will ever see it.

Status Codes
POST /api/admin

Handles POSTs for the various forms on the main admin-page.

Status Codes
GET /api/admin/search

Returns a simple htmlpage that lets admins search for subscriptions and perform various operations on them.

Query Parameters

  • search_type (string) – The type of items to search for.

  • query (string) – Specifies the text to filter search for. An empty string means to display all the items of the selected type.

  • search_in_all_fields (boolean) – If this is set to false (the default), the query-text will only be matched against a few selected fields (name and id, usually). If it is set to true, the query-text will be matched against all the fields.

Status Codes
POST /api/admin/search

Handles POSTs for the various forms on the search-page.

Status Codes
GET /api/admin/portal_administrators

Returns a simple htmlpage that display the current portal admins.

Status Codes
POST /api/admin/portal_administrators

Handles POSTs for the various forms on the portal_admins-page.

Status Codes
GET /api/admin/delete_user

Returns a simple htmlpage that lets the admin delete users

Status Codes
POST /api/admin/delete_user

Handles POSTs for the various forms on the delete_user-page.

Status Codes
POST /api/admin/throw_exception

This is a test-endpoint for throwing various exceptions. This is used in ci-tests to verify that exceptions of various types are logged correctly.

Status Codes
GET /api/admin/config_gui

Returns a gui for examining and modifying the portal configuration.

Status Codes
GET /api/admin/pre_created_subscriptions

Returns a gui for examining and modifying the “pre-created subscriptions” settings.

Status Codes
GET /api/admin/config

Returns the current runtime configuration of the Portal. This is config that is intended to be modified at runtime (as opposed to stuff like database usernames and passwords, which is specified in the sesamportal.yaml file). See the definition of the ConfigEntity model and it’s child models.

Status Codes
Response JSON Object

  • []._id (string) – (required)

  • [].type (string) – (required)

POST /api/admin/config

Adds one or more new runtime configuration entries to the Portal.

Request JSON Object

  • []._id (string) – (required)

  • [].type (string) – (required)

Status Codes
PUT /api/admin/config/validation_hack_for_SubscriptionJWT

This is a dummy endpoint that is used to register the SubscriptionJWT definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Request JSON Object

  • audit.created_by.email (string) –

  • audit.created_by.name (string) –

  • audit.created_by.picture (string) –

  • audit.created_by.user_id (string) –

  • audit.created_ts (string) –

  • audit.last_modified_by.email (string) –

  • audit.last_modified_by.name (string) –

  • audit.last_modified_by.picture (string) –

  • audit.last_modified_by.user_id (string) –

  • audit.last_modified_ts (string) –

  • client_id (string) – Optional. The ‘client_id’ (if any) associated with this JWT. This is only present for tokens where the refresh_interval has been set.

  • client_secret (string) – Optional. The ‘client_secret’ (if any) associated with this JWT. For security-reasons this is only returned when the JWT is created. This is only present for tokens where the refresh_interval has been set.

  • description (string) – A user-assigned description of this token. (required)

  • id (string) – The internal id of the token (required)

  • jwt_string (string) – The actual signed JWT. For security-reasons this is only returned when the JWT is created.

  • name (string) – A user-assigned name for this token. (required)

  • payload.api_token_id (string) – The id of this JWT api token. We need a copy of the id in the payload, since the sesam-node needs to be able to retrieve it in order to check if the token has been invalidated. (required)

  • payload.exp (number) – Standard “expiration time” field. This is measured in the number of seconds since the Epoch. Note that if the ‘refresh_interval’ parameter is set, this is not the “exp” value that will actually be in the jwt_string; instead the value will be “current_time + refresh_interval” (required)

  • payload.iat (number) – Standard “issued at” field. This is measured in the number of seconds since the Epoch. (required)

  • payload.principals (object) – This is a mapping from subscriptionid to the list of principals for that subscription. The reason we have a mapping is that our JWTs can contain potentially contain permissions for more than one subscription. In this case there will alwasy be exactly one subscription_id in this mapping (i.e. for the subscription that this api jwt belongs to). (required)

  • payload.user_id (string) – (required)

  • payload.user_principal (string) – This is the principal that normally represents the user itself. This is always set to ‘group:Everyone’ for api JWTs.

  • payload.user_profile.email (string) –

  • payload.user_profile.name (string) –

  • payload.user_profile.picture (string) – An URL pointing to an (avatar-)picture of the user

  • refresh_interval (number) – Optional. Specifies the interval (in seconds) at which the token must be refreshed.

  • supported-operations.delete_api_jwt_token (any) – (required)

Status Codes
PUT /api/admin/config/validation_hack_for_AllowedProvidersForDomains

This is a dummy endpoint that is used to register the AllowedProvidersForDomains definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/validation_hack_for_AutoJoinSubscriptionGroup

This is a dummy endpoint that is used to register the AutoJoinSubscriptionGroup definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/validation_hack_for_PreCreatedSubscription

This is a dummy endpoint that is used to register the PreCreatedSubscription definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/validation_hack_for_RateLimits

This is a dummy endpoint that is used to register the RateLimits definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/{config_entity_id}

Updates the specified configuration entry.

Parameters

  • config_entity_id (string) – The config entity id

Request JSON Object

  • _id (string) – (required)

  • type (string) – (required)

Status Codes
GET /api/admin/config/{config_entity_id}

Returns the specified configuration entry.

Parameters

  • config_entity_id (string) – The config entity id

Status Codes
Response JSON Object

  • _id (string) – (required)

  • type (string) – (required)

DELETE /api/admin/config/{config_entity_id}

Deletes the specified configuration entry.

Parameters

  • config_entity_id (string) – The config entity id

Status Codes
GET /api/subscriptions/{subscription_id}/subscription-settings

This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to get notified when a user has done something that changes a subscription’s settings. For instance, this is used by the self-service multinode to retrieve the ip-filtering rules to use.

Parameters

  • subscription_id (string) – The subscription id

Query Parameters

  • since (integer) – Specifies that the endpoint should only return entities newer than the specified ‘since’ value. The since-value should be set to the value of the “_updated”-attribute in the last seen entity. See https://docs.sesam.io/hub/features/continuation-support.html for details on how this works.

Status Codes
Response JSON Object

  • []._id (string) – (required)

  • []._updated (any) – This is a version-value that is used to implement optimistic locking on the server. Note that this value can be of any type, so the client shouldn’t make any assumptions about it. (required)

  • [].audit.created_by.email (string) –

  • [].audit.created_by.name (string) –

  • [].audit.created_by.picture (string) –

  • [].audit.created_by.user_id (string) –

  • [].audit.created_ts (string) –

  • [].audit.last_modified_by.email (string) –

  • [].audit.last_modified_by.name (string) –

  • [].audit.last_modified_by.picture (string) –

  • [].audit.last_modified_by.user_id (string) –

  • [].audit.last_modified_ts (string) –

  • [].created (string) – (required)

  • [].description (string) – A short description of the subscription.

  • [].name (string) – (required)

  • [].network.network-acl[].access (string) – (required)

  • [].network.network-acl[].address (string) – (required)

  • [].network.public-access (boolean) –

  • [].products.databrowser[].custom_fqdn[] (string) –

  • [].products.databrowser[].id (string) – (required)

  • [].products.databrowser[].name (string) –

  • [].products.databrowser[].size (string) –

  • [].products.databrowser[].type (string) – This is only set when the databrower is being used in a gdpr platform

  • [].products.datahub.backup (string) –

  • [].products.datahub.byok (boolean) – Setting this to true enables the “Bring Your Own Keys” feature in Azure. See this page for some background on the BYOK feature: https://docs.microsoft.com/en-us/azure/information-protection/byok-price-restrictions Note that enabling this feature incurs additional costs.

  • [].products.datahub.developer_mode (boolean) – This is a property that is set in some subscriptions to allow certain APIs such as reset node that is dangerous to enable in a production environment

  • [].products.datahub.fixed_price_gb (integer) – This property specifies the number of GBs that are set as the threshold for the subscription fixed price payment scheme. If this property exists, subscription is invoiced using fixed price scheme.

  • [].products.datahub.maximum_store_disk_usage (integer) – This is a read-only property that is set in some special cases where a custom server has been set up by sesam employees. It specifies the maximum size of the data store in bytes.

  • [].products.datahub.monitoring (string) – This can be set to “standard” to enable monitoring for this subscription (this currently requires some manual work by SESAM employees).

  • [].products.datahub.size (string) – This property describes the size of the node. As of Sep 2021, small, medium, large and xlarge are legacy sizes. The UI maps small/medium to single and xlarge to multi. (required)

  • [].products.datahub.version (string) – The docker tag that the user wants the sesam-node container to use. The docker tag that is currently in use is specified in the “provisioning_result”->”datahub”->”tag” property. There will always be a delay between the time the user changes the “version”-property and the time when the “provisioning_result”->”datahub”->”tag” property changes; at the very least the sesam-node needs to be stopped and restarted with the new docker-image.

  • [].products.gdpr_platform.custom_fqdn[] (string) –

  • [].products.gdpr_platform.name (string) – An optional, humanreadable name for this gdpr platform.

  • [].products.gdpr_platform.size (string) – (required)

  • [].products.microservices.size (string) – (required)

  • [].products.search (boolean) – This controls whether to activate the search capability

  • [].products.sla.level (string) – (required)

  • [].products.vpn.connections[]._id (integer) – This is an internal unique id that is assigned to new vpn-connections by the backend. The GUI will not display this value, but will include it as-is in PUT-requests. (The portal backend uses this value to replace the placeholder “****” for the shared_key property in PUT-requests; it needs a way to uniquely identify connections).

  • [].products.vpn.connections[].address_spaces[] (string) –

  • [].products.vpn.connections[].gateway_address (string) –

  • [].products.vpn.connections[].shared_key (string) – This is the secret shared key that is used to authenticate against the VPN. This property is write-only and will always look like “****” in the api-responses from the backend. If the special value “****” is used in a PUT-request, the value is ignored and the current shared_key value will not be changed. The intention is that the GUI can display and send the shared_key value as-is.

  • [].products.vpn.dns[] (string) –

  • [].products.vpn.enable_snat (boolean) –

  • [].products.vpn.local-range (string) –

  • [].products.vpn.local-subnet (string) –

  • [].products.vpn.onsite-ranges[] (string) –

  • [].products.vpn.public-gateway (string) –

  • [].products.vpn.sesam_address_spaces[] (string) –

  • [].products.vpn.sesam_gateway (string) –

  • [].products.vpn.tier (integer) –

  • [].products.vpn.type (string) –

  • [].provisioning_settings.kubernets_upgrade_channel (string) – The upgrade channel to use to auto-upgrade the kubernetes cluster. See https://docs.microsoft.com/en-us/azure/aks/upgrade-cluster#set-auto-upgrade-channel for a detailed explanation and for a list of available channels.

  • [].provisioning_settings.max_workers (integer) – The maximum number of server machines this subscription is allowed to use.

  • [].provisioning_settings.num_workers (integer) – The number of server machines this subscription currently uses.

  • [].type (string) – This can be set to ‘trial’ in order to create a trial subscription. It is only legal to set this to true if the ‘create_trial_subscription’-operation (from the ‘supported-operations’ from /api/profile) is enabled and all the various ‘size’ and ‘level’ settings on the subscription is at their minimum values.

  • [].url (string) – An URL that points to a web-page that is related to the subscription somehow. This url just for human consumption, and would typically be used to point to the home-page of a project, or a wiki-page that describes what the sesam-installation does.

GET /api/subscriptions/{subscription_id}/pipe-settings

Returns a list of pipe-setting dicts. This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to get notified when a user has done something that changes a pipe’s monitoring requirements.

Parameters

  • subscription_id (string) – The subscription id

Query Parameters

  • since (string) – Specifies that the endpoint should only return entities newer than the specified ‘since’ value. The since-value should be set to the value of the “_updated”-attribute in the last seen entity. See for details on how this works.

Status Codes
Response JSON Object

  • []._deleted (boolean) – This is set to true if the entry for the pipe has once existed, but should now be removed.

  • []._id (string) – This is the id of the pipe that this entry describes. (required)

  • []._updated (any) – An opaque value that can be used as the value of the “since” parameter in a later call.

  • [].insights_enabled (boolean) – Specifies if the “Insights”-tab should be displayed for this pipe. (required)

  • [].monitoring_settings.log_events.batch-write-error.triggers[] (string) –

  • [].monitoring_settings.log_events.pump-completed.triggers[] (string) –

  • [].monitoring_settings.log_events.pump-failed.triggers[] (string) –

  • [].monitoring_settings.log_events.pump-started.triggers[] (string) –

  • [].monitoring_settings.log_events.read-error.triggers[] (string) –

  • [].monitoring_settings.log_events.write-error.triggers[] (string) –

PUT /api/subscriptions/{subscription_id}/pipe-settings/{pipe_id}

Update the settings of the specified pipe.

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

Status Codes
Response JSON Object

  • _updated (any) – This is required for optimistic locking and should be included if there already existed a pipe-settings entry for the pipe.

  • insights_enabled (boolean) – Specifies if the “Insights”-tab should be displayed for this pipe.

GET /api/subscriptions/{subscription_id}/pipe-settings/{pipe_id}

Returns the settings of the specified pipe.

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

Status Codes
Response JSON Object

  • _deleted (boolean) – This is set to true if the entry for the pipe has once existed, but should now be removed.

  • _id (string) – This is the id of the pipe that this entry describes. (required)

  • _updated (any) – An opaque value that can be used as the value of the “since” parameter in a later call.

  • insights_enabled (boolean) – Specifies if the “Insights”-tab should be displayed for this pipe. (required)

  • monitoring_settings.log_events.batch-write-error.triggers[] (string) –

  • monitoring_settings.log_events.pump-completed.triggers[] (string) –

  • monitoring_settings.log_events.pump-failed.triggers[] (string) –

  • monitoring_settings.log_events.pump-started.triggers[] (string) –

  • monitoring_settings.log_events.read-error.triggers[] (string) –

  • monitoring_settings.log_events.write-error.triggers[] (string) –

DELETE /api/subscriptions/{subscription_id}/pipe-settings/{pipe_id}

Deletes the settings of the specified pipe.

Parameters

  • subscription_id (string) – The subscription id

  • pipe_id (string) – The pipe id

Status Codes
GET /api/subscriptions/{subscription_id}/revoked_json_web_tokens

Returns a list of revoked json web tokens. Note that this includes both the transient JWTs that are issued by the unified GUI to talk to the node, and the special API JWTs that are typically very long-lived. This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to get notified when a user’s permissions have been modified, and when an api JWT has been revoked.

Parameters

  • subscription_id (string) – The subscription id

Query Parameters
Status Codes
Response JSON Object

  • []._id (string) – (required)

  • []._updated (any) – An opaque value that can be used as the value of the “since” parameter in a later call. (required)

  • [].api_token_id (string) – The id of the API JWT to invalidate. This refers directly to one specific API JWT. This property is mutually exclusive with the ‘user_principal’ parameter, each entity will have either a ‘user_principal’ parameter or a ‘api_token_id’ parameter, but never both.

  • [].revoked_by.email (string) –

  • [].revoked_by.name (string) –

  • [].revoked_by.picture (string) –

  • [].revoked_by.user_id (string) –

  • [].revoked_ts (string) – The time this revocation happened. (required)

  • [].subscription_id (string) – The subscription this revocation applies to. (required)

  • [].user_principal (string) – The user_principal to invalidate regular (non-api) JWTs for. This tells the subscription-node that all JWTs for the specified user_principal that has been created before the revoked_by time are invalid. This property is mutually exclusive with the ‘api_token_id’ parameter, each entity will have either a ‘user_principal’ parameter or a ‘api_token_id’ parameter, but never both.

GET /api/subscriptions/{subscription_id}/updated_licences

Returns a list of updated licenses. This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to get notified when a subscription’s lisence has been upgraded.

Parameters

  • subscription_id (string) – The subscription id

Query Parameters
Status Codes
Response JSON Object

  • []._deleted (boolean) – true if this lisence is obsolete. (required)

  • []._id (string) – (required)

  • []._updated (any) – An opaque value that can be used as the value of the “since” parameter in a later call. (required)

  • [].signed (string) – The signed license key. This is only present for ‘on-premise’ subscriptions. For ‘in-cloud’ subscriptions the license-key is handled by the provisioner service and should never be shown to the customer. (required)

POST /api/subscriptions/{subscription_id}/resource-needs

This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to specify that more hardware resources are required.

Parameters

  • subscription_id (string) – The subscription id

Request JSON Object

  • datahub (object) – This property is deprecated. Use ‘provisioning_settings’ instead.

  • provisioning_settings.num_workers (integer) – Specifies that the number of worker boxes that this subscription needs. (required)

Status Codes
GET /api/provisioning/domain

Returns information about availability of a domain name.

Query Parameters

  • fqdn (string) –

  • subscription_id (string) –

Status Codes
Response JSON Object

  • available (boolean) – (required)

  • content (string) –

  • fqdn (string) – (required)

  • message (string) –

  • ttl (integer) –

  • type (any) –

POST /api/feedback

Submits feedback from the feedback form to Slack

Request JSON Object

  • message (string) – The message body of the feedback

  • path (string) – The path from where the feedback was submitted

  • user_email (string) – The email of the sender

Status Codes
GET /.well-known/openid-configuration

This endpoint returns the “OpenID Provider Configuration Response”, as described at https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse

Status Codes
POST /api/openid_connect/token

This is the “OpenID Connect Token endpoint”, as described at https://tools.ietf.org/html/rfc6749#section-3.2

Status Codes

Swagger Files

To access the Swagger endpoint for your instance go to https://<your-instance>/api/reference.

For the Portal API go to the Autogenerated Swagger Endpoint for the Portal.

Config groups

See the config groups API for more information.

Metrics endpoint

If Monitoring and Metrics is enabled, you can access subscription and pipe metrics in the Prometheus-compatible metrics API endpoint from your external monitoring tools.

previous

Quick Reference

next

Service Configuration Guide