Skip to main content

Getting started

Welcome to Sovrin API!

By now, you should have been provided with the following details, required for accessing and engaging with your Sovrin API tenant:

tip

If you have not received these details or have any questions, please contact us before proceeding.

{
    "tenantSubdomain": "YOUR_TENANT_SUBDOMAIN",
    "tenantId": "YOUR_TENANT_ID",
    "url": "YOUR_AUTH_URL",
    "audience": "YOUR_AUDIENCE_URL",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}

  • tenantSubdomain: Your Sovrin API tenant subdomain URL. You will use it to make API requests to your tenant.

  • tenantId: Your tenant's unique identifier.

  • url: Our authentication provider URL. You will use it to complete authentication.

  • audience: The Sovrin API server your tenant will access. You will use it to complete authentication.

  • client_id: Unique id for accessing your Sovrin API tenant. You will use it to complete authentication.

  • client_secret: Unique secret for accessing your Sovrin API tenant. You will use it to complete authentication.

Authentication​

Before you can make any API requests to your Sovrin API tenant, you must complete authentication by obtaining an API access token from our authentication provider. Refer to the authentication section of the API Reference for more information.

Use values from your tenant details to make the following request:

Request​

POST https://{auth_server}/oauth/token
  • auth_server: Replace with the url value from your tenant details.
{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "YOUR_AUDIENCE_URL",
    "grant_type": "client_credentials"
}

  • client_id: Replace with the client_id value from your tenant details.

  • client_secret:Replace with the client_secret value from your tenant details.

  • audience: Replace with the audience value from your tenant details.

  • grant_type: Use client_credentials.

Response​

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "expires_in": 14400,
    "token_type": "Bearer"
}

The returned access_token value must be used as a bearer token for all subsequent requests to protected resources on your tenant.

Verify your access token​

A good test to ensure that you can access your Sovrin API tenant is to retrieve a list of DIDs.

First, use the tenantSubdomain value from your tenant details to construct the URL you will use to make API requests to your tenant:

https://{tenant_Subdomain}.api.est.sovrin.network
  • tenant_Subdomain: Replace with the tenantSubdomain value from your tenant details.
tip

This is the base URL you should use for all API requests to your tenant, suffixed by the required endpoint. This URL is referenced as api.sovrin.one across our tutorials.

Request​

Use your tenant URL and the returned bearer token to make the following request:

GET https://api.sovrin.one/v1/dids

Response​

Success is indicated by a returned 200 HTTP status code. As you’ve likely not yet created any DIDs, we would expect an empty array as a response:

[] The fact that a 200 HTTP status code was returned indicates that your bearer token has permitted access to the protected resource.

tip

We recommend using our Postman collection to interact with your Sovrin API tenant. This collection includes a pre-request script to obtain an access token when it is missing or expired.

What's next?​

You are now ready to start creating your digital trust ecosystem:

  • Learn more about the fundamentals of digital trust ecosystems in our Docs section.

  • Get hands on Sovrin API experience in our Tutorials section.

  • Browse all available Sovrin API APIs in our API Reference.