Skip to main content

Provisioning a New Tenant

This section covers the steps to provision a new tenant in the Stellar Disbursement Platform (SDP). A tenant is an isolated organization or entity that uses the SDP to manage disbursements. Each tenant has its own configuration settings, users, disbursements, and most importantly, its own source of funds.

The endpoints needed to manage tenants can be found in the Admin (Tenant Management) docs.

Creating Tenants​

Tenants can be created through the POST /tenants endpoint. As a quickstart, you can execute the main.sh script from our repository and make sure to replace it with the desired values.

The following sections detail how each field is used on the provisioning process and, so you can ensure the tenants are provisioned as expected:

distribution_account_type​

This is by far the most important field, as it determines the source of funds (distribution account) for the tenant, as well as how the secret for this distribution account is stored. The possible values are described below:

  • DISTRIBUTION_ACCOUNT.STELLAR.DB_VAULT
    • Platform: Stellar
    • Secret Storage Location: Database, encrypted with DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE
    • Assets Supported: Any Stellar asset
    • Key/Secret Isolation: Segregated per tenant
    • Appropriate for: Multi-tenant and single-tenant
    • How is it configured?: The distribution account is randomly generated and funded during the provisioning process, and the secret is encrypted and safely stored in the database.
    • Transaction throughput: Aproximately 40 transactions per second.
  • DISTRIBUTION_ACCOUNT.CIRCLE.DB_VAULT
    • Platform: Circle
    • Secret Storage Location: Database, encrypted with DISTRIBUTION_ACCOUNT_ENCRYPTION_PASSPHRASE
    • Assets Supported: USDC/EURC
    • Key/Secret Isolation: Segregated per tenant
    • Appropriate for: Multi-tenant and single-tenant
    • How is it configured?: The Circle API key is provided by the tenant themselves once they have access to the dashboard. The secret is encrypted and safely stored in the database.
    • Transaction throughput: ⚠️ Limited by Circle's API rate limits.
  • 🔴 DISTRIBUTION_ACCOUNT.STELLAR.ENV
    • Platform: Stellar
    • Secret Storage Location: Environment variable DISTRIBUTION_SEED
    • Assets Supported: Any Stellar asset
    • Key/Secret Isolation: 🚨 Same distribution account as the HOST
    • Appropriate for: Single-tenant only
    • How is it configured?: The tenant will use the HOST account as is. The host is responsible for creating the account and configuring it with the DISTRIBUTION_SEED secret.
    • Transaction throughput: Aproximately 40 transactions per second.
info

Once a tenant is created, the distribution_account_type cannot be changed. If you wish to use a different distribution account type, you will need to create a new tenant.

name​

This is the name of the tenant in the admin database. It is used to generate the per-tenant database schema, and is also used in the dashboard to identify the tenant.

It cannot be changed once the tenant is created.

base_url, and sdp_ui_base_url​

These are the URLs that the tenant will use to access the API and the dashboard, respectively. They are used to generate the tenant-specific URLs that are used in the dashboard and the user-targeted or receiver-targeted messages.

They are important to allow the SDP backend to route the unauthenticated requests to the correct tenant, and to generate the correct URLs in the dashboard.

owner_email, owner_first_name, and owner_last_name​

This is the information of the first user in the tenant organization. This user will have the OWNER role, which grants them full access & control to the tenant.

The email, first name, and last name can be updated by the user themselvses once they sign up and access the dashboard.

organization_name​

This fields is used to populate the tenant's name in the dashboard. It can be updated by the owner user through the dashboard.

Single-tenant Mode​

The platform is designed for multi-tenant mode, but it can also be used in single-tenant mode. This is the only case when setting DISTRIBUTION_ACCOUNT.STELLAR.ENV is acceptable, while the other modes are still advised.

To enable signle-tenant mode, tiy need to follow two steps:

  1. Set the env SINGLE_TENANT_MODE=true.
  2. As a HOST, you need to update the database by configuring which tenant is the default one by calling POST /tenants/default-tenant
caution

Once this SINGLE_TENANT_MODE env is enabled, all tenant-related requests will expect there to be a default tenant and will fail with a 400 status code if there isn't one. The API response will include a message indicating that the default tenant is missing.

Fetching Tenants​

The tenants can be fetched through the GET /tenants and GET /tenants/:id-or-name endpoints.

Deleting Tenants​

Tenants can be deleted through the DELETE /tenants/:id endpoint. This is a soft deletion though and despite the system not providing a way to ubdelete it, the tenant information won't be deleted from the database with the current implementation.

Updating Tenants​

Some fields of a tenant can be updated through the PATCH /tenants/:id endpoint. The API documentation provides more details on which fields can be updated.