Learn

Tenant setup

Introduction

A good test to ensure that your newly-established tenant in MATTR VII is working correctly is to retrieve an API access token and then use that token to retrieve a list of DIDs and/or create a DID.

Prerequisites

As a MATTR VII user, you are supplied with the requisite credentials via an out-of-band onboarding process as follows:

json
Copy to clipboard. 
1{
2    "tenantSubdomain": "YOUR_TENANT_URL",
3    "tenantId": "d97H2lc0-3ht5-4bea-ht92-41052f047440",
4    "url": "https://auth.mattr.global/oauth/token",
5    "audience": "https://vii.mattr.global",
6    "client_id": "YOUR_CLIENT_ID",
7    "client_secret": "YOUR_CLIENT_SECRET"
8}

If you have not received these credentials or have questions, contact us before proceeding.

Authorization

Use the client_id and client_secret provided to construct a request and then make a call to the authorization provider and obtain an API access token.

Request

http
Copy to clipboard. 
1POST https://auth.mattr.global/oauth/token
json
Copy to clipboard. 
1{
2  "client_id": "YOUR_CLIENT_ID",
3  "client_secret": "YOUR_CLIENT_SECRET",
4  "audience": "https://vii.mattr.global",
5  "grant_type": "client_credentials"
6}

Response

json
Copy to clipboard. 
1{
2  "access_token": "YOUR_ACCESS_TOKEN",
3  "expires_in": 86400,
4  "token_type": "Bearer"
5}

The access_token value returned will be used as the bearer token for all subsequent requests to protected resources.

Take a look at the authorization section of the API Reference for more information.

Retrieve DIDs

Try to retrieve a list of DIDs to verify that the bearer token permits access to protected APIs. Success is indicated by a returned 200 HTTP status code - as you’ve likely not yet created any DIDs we would expect the body of the response to be an empty array.

Request

Using the newly-acquired access token, make a GET request to the /v1/dids endpoint using the subdomain issued to you.

http
Copy to clipboard. 
1GET https://YOUR_TENANT_URL/v1/dids

Going forward examples will use YOUR_TENANT_SUBDOMAIN.vii.mattr.global to denote the domain. You will need to replace YOUR_TENANT_SUBDOMAIN with the specific tenantSubdomain provided with your credentials.

This is an example in cURL:

shell
Copy to clipboard. 
1curl --request GET \
2  --url https://YOUR_TENANT_URL/core/v1/dids \
3  --header 'Accept: application/json' \
4  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

Assuming you haven’t yet created any DIDs, this request returns an empty array:

[]

The fact that a 200 HTTP status code was returned indicates that your bearer token has permitted access to the protected API. The empty array returned simply indicates that no DIDs have been created within the tenant - let's change that now.

Create a DID

Now that we’ve verified that you have access, let’s do something meaningful and create a DID on your tenant. A reasonable first DID method to use is the did:key method.

Request

http
Copy to clipboard. 
1POST https://YOUR_TENANT_URL/v1/dids
json
Copy to clipboard. 
1{
2  "method": "key"
3}

Response

json
Copy to clipboard. 
1{
2  "did": "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX",
3  "registrationStatus": "COMPLETED",
4  "localMetadata": {
5    "keys": [
6      {
7        "didDocumentKeyId": "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX#z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX",
8        "kmsKeyId": "FiBZLe1WzR9LDJ9jpqYMaEYrUgSuCY8ULDzAHVV2Mzh9"
9      },
10      {
11        "didDocumentKeyId": "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX#z6LSgjkRLLbm634tqaMMtrwmk1svFDVEeGX4ke25A8o72ter",
12        "kmsKeyId": "64aFp2ntzaM9kBybNDRpRRfSQ4x7wfLusfJPfg9aKWt6"
13      }
14    ],
15    "registered": 1601004096785,
16    "initialDidDocument": {
17      "@context": "https://w3.org/ns/did/v1",
18      "id": "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX",
19      "publicKey": [
20        {
21          "id": "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX#z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX",
22          "type": "Ed25519VerificationKey2018",
23          "controller": "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX",
24          "publicKeyBase58": "FiBZLe1WzR9LDJ9jpqYMaEYrUgSuCY8ULDzAHVV2Mzh9"
25        }
26      ],
27      "authentication": [
28        "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX#z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX"
29      ],
30      "assertionMethod": [
31        "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX#z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX"
32      ],
33      "capabilityDelegation": [
34        "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX#z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX"
35      ],
36      "capabilityInvocation": [
37        "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX#z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX"
38      ],
39      "keyAgreement": [
40        {
41          "id": "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX#z6LSgjkRLLbm634tqaMMtrwmk1svFDVEeGX4ke25A8o72ter",
42          "type": "X25519KeyAgreementKey2019",
43          "controller": "did:key:z6MkuASbvtFxKxdoKnzSWQWCRL6rJFikcRNq2Eu67mT3HDUX",
44          "publicKeyBase58": "64aFp2ntzaM9kBybNDRpRRfSQ4x7wfLusfJPfg9aKWt6"
45        }
46      ]
47    }
48  }
49}

Next steps

You are now ready to configure your tenant for your use case. You can head to the Tutorials section to discover the different options available to you. For instance, to learn more about the importance of DIDs within MATTR VII, take a look at our overview of DID use.