Onboard tenant

General flow

The Sharespine API consists of two distinct areas, the Reseller- and the Tenant API.

Reseller: A Reseller can use the Reseller API to create new tenants, tenant users, connections and to access some basic information of the tenants.
Tenant: A Tenant’s data can be accessed through the Tenant API e.g order, product etc. The tenant needs an active API-connection and a tenant user to enable API-access.

Steps:

Create user environment (tenant)
Create tenant user to use when accessing the tenant via API
Create an API-connection. Activate API-access for the tenant
Get an URL that will sign in the user automatically
Send the user to the received URL so that they can do the configuration
Fetch orders from the tenant on a regular basis.

sequenceDiagram participant Customer participant Reseller participant ResellerAPI participant TenantAPI alt new customer Customer->>Reseller: Request new service Reseller->>ResellerAPI: Create tenant Note right of ResellerAPI: Tenant created Reseller->>ResellerAPI: Create tenant user Reseller->>ResellerAPI: Add API connection Reseller->>ResellerAPI: Request login url ResellerAPI->>Reseller: Return temporary login url Reseller->>Customer: Redirect user to login url end alt returning customer Customer->>Reseller: Request service Reseller->>ResellerAPI: Request login url ResellerAPI->>Reseller: Return temporary login url Reseller->>Customer: Redirect user to login url end Reseller->>TenantAPI: Request data (e.g orders) TenantAPI->>Reseller: Return data

Create tenant

Create one tenant per customer account. The created tenant will get a unique codeName, save this codeName.

customerReference: Your reference for the customer and the information will be used when creating a codeName for the tenant. For example if the customerReference is mycustomer then the codeName could be prefixmycustomer-number. Use lowercase for best support.
active: Normally true but a tenant can be deactivated if the customer wants to temporarily stop using the service. Delete the tenant if the customer really cancels the service (all data will be lost).
options: A list of options needed to access the functionality in the tenant. A full list will be provided at start of project.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Reseller: <RESELLER CODE>' \
    https://api.{HOSTNAME}/reseller/tenant \
    -XPOST \
    -d \
    '{
        "customerReference": "string",
        "active": true,
        "fullName": "string",
        "email": "string",
        "defaultLanguage": "swe",
        "languages": [
            "swe"
        ],
        "options": [
            "string"
        ]
    }'

Response Save the value from codeName, it will be used later when accessing the tenant.

{
    "codeName":"aCodeName"
 }

API-references

Tenant

Create tenant user

Create one tenant user for every user that should access the tenant. If your system has multiple users that can load the Wizard then create one tenant user for each.

Also create an API user that can be used to access the tenant API for the specific tenant.

login: A login for the tenant user. (This should be unique within the tenant)
permissions: A list with required permissions. A full list will be provided at start of project.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Reseller: <RESELLER CODE>' \
    https://api.{HOSTNAME}/reseller/tenant/{codeName}/user \
    -XPOST \
    -d \
    '{
        "login": "string",
        "fullName": "string",
        "email": "string",
        "permissions": [
            "string"
        ],
        "defaultLanguage": "swe"
    }'

Response Check that the user was created and save the login (same as defined in the request).

{
    "login": "string",
    "....": "...."
 }

API-references

Tenant User

Create an API Connection

An API connection is needed to access the tenant API for a specific tenant.

type: Type of connection. Default connector type for the API-connector is api.
configuration: A list with connection configuration. A full list will be provided at start of project.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Reseller: <RESELLER CODE>' \
    https://api.{HOSTNAME}/reseller/tenant/{codeName}/connection \
    -XPOST \
    -d \
    '{
        "active": true,
        "name": "API",
        "type": "api",
        "configuration": {}
    }'

Response Save the id from the response. That id is needed as a part for auth to the tenant API.

{
    "id": "00076ad40b558ecd874c5482108409ad",
    "type": "api",
    "....": "...."
 }

API-references

Tenant User

Create a login URL for specific tenant user

Do this call to get a login url for a user and redirect the user to the retrieved url.

path: Where to redirect the user after login.

Request

$ curl \
    -u '<USERNAME>':'<PASSWORD>' \
    -F 'User-Agent: my-app/1.0 (YOURADDRESS@example.com)' \
    -H 'X-Reseller: <RESELLER CODE>' \
    https://api.{HOSTNAME}/reseller/tenant/{codeName}/login/{login} \
    -XPOST \
    -d \
    '{
        "path":"/"
    }'

Response

{
    "path": "/",
    "loginUrl": "https://my.[env].plugboard.io/_tokenlogin/{login}/{unique_random_id})",
    "expires": "2023-04-04T13:57:16Z"
 }

Redirect the user to the loginUrl and the user will be logged in to the tenant user interface.

Access tenant data

The reseller have access to access a limit amount of information through the Reseller API. See the current supported endpoints at Reseller API Tenant

To access all the tenant data use the Tenant API. This requires an api-connector and a tenant user for the specific tenant.

Next: Tools