Skip to main content

Manage tenants

This tutorial will introduce you to available tenant management capabilities:

Before you begin​

Make sure you have obtained an access token before making any API requests.

Create a tenant​

Make the following request to create a new tenant in your environment:

Request​

POST https://manage.sovrin.network/v1/tenants
{
  "name": "My First Tenant",
  "subdomain": "tenants-test-subdomain",
  "environmentId": "4b69a1d6-1f4d-4df7-a149-c4bb89c5d000"
}

  • name: The name that will be used to identify this tenant.

  • subdomain: The subdomain that will be used to access this tenant. Only lower case alphanumeric characters (a-z, 0-9) and hyphens are allowed.

  • environmentId: This identifier will be provided to you by Sovrin as part of onboarding to the Management API capability. Contact us if you did not receive it.

Response​

{
    "id": "6facbcef-66cd-4a06-89e3-e44a4fc12000",
    "name": "My First Tenant",
    "subdomain": "tenant-test-subdomain.api.est.sovrin.network",
    "environment": {
        "id": "4b69a1d6-1f4d-4df7-a149-c4bb89c5d000",
        "name": "Public Estonia Tallinn",
        "domain": "api.est.sovrin.network",
        "deploymentModel": "public",
        "authorizationServerDomain": "auth.manage.sovrin.network",
        "region": {
            "id": "0fd6ce12-a983-41d0-aca8-03e1bb6f6000",
            "name": "est",
            "displayName": "Tallinn, Estonia"
        }
    },
    "client": {
        "clientId": "MjQx108p***************FlwJQjy",
        "clientSecret": "NanfSkVr**********************PfD3zJ"
    }
}

  • id: Globally unique tenant identifier.

  • name: The name you set in the request.

  • subdomain: The tenant URL, constructed with the subdomain you set in the request.

  • environment: Indicates environment data.

  • client: Indicates the tenant clientId and clientSecret. Make sure you store these securely for future authentication. The clientSecret cannot be retrieved again after this point.

Delete a tenant​

The Management API provides the ability to soft-delete a tenant. The tenant is no longer available through the Management API, but its data is not removed and the tenant itself remains accessible through authentication with its original client ID and secret.

tip

If you wish to permanently delete your tenant and its data, please contact us.

Make the following request to soft-delete a tenant based on its identifier:

Request​

DELETE https://manage.sovrin.network/v1/tenants/TENANT_ID
  • TENANT_ID: Replace with the tenant identifier obtained when it was created.

Response​

Status Code: 204 No Content

The 204 response indicates a succesful deletion.

List tenants​

Make the following request to retrieve a list of tenants in your environment:

Request​

GET https://manage.sovrin.network/v1/tenants

Response​

{
    "data": [
        {
            "id": "6facbcef-66cd-4a06-89e3-e44a4fc12000",
            "name": "My First Tenant",
            "subdomain": "tenant-test-subdomain.api.est.sovrin.network",
            "environment": {
                "id": "4b69a1d6-1f4d-4df7-a149-c4bb89c5d000",
                "name": "Public Estonia Tallinn",
                "domain": "api.est.sovrin.network",
                "deploymentModel": "public",
                "authorizationServerDomain": "auth.manage.sovrin.network",
                "region": {
                    "id": "0fd6ce12-a983-41d0-aca8-03e1bb6f6000",
                    "name": "est",
                    "displayName": "Tallinn, Estonia"
                }
            }
        }
    ]
}

Success is indicated by a returned 200 HTTP status code. If you haven’t created any tenants yet, this request will return an empty array.

tip

By default you only have access to tenants that you have created using your Management API credentials. If you wish to access additional tenants, please contact us.

Retrieve your client ID​

To access your tenant, you will need a clientId and a clientSecret. Make the following request to retrieve the clientId for a given tenant:

Request​

GET https://manage.sovrin.network/v1/tenants/TENANT_ID/clients
  • TENANT_ID: Replace with the tenant identifier obtained when it was created.

Response​

{
    "clientId": "MjQx108p***************FlwJQjy"
}
tip

The tenant's clientSecret is only available when initially creating a tenant and cannot be retrieved at a later point.

What's next?​

After creating your tenant and recording its credentials, you get started with using it.