> For the complete documentation index, see [llms.txt](https://docs.borlaug.services/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.borlaug.services/api/identity/dids.md).

# DIDs

## Register a new DID

<mark style="color:green;">`POST`</mark> `https://api.borlaug.network/identity/dids`

Registers a new DID for the caller. By creating a new DID the caller also becomes a controller of the newly created DID.\
\
If **`catalogid`** is provided, DID is registered and added to this catalog owned by the controller with the given **`short_name`**.\
\
If **`properties`** array is provided, DID is registered with them.

#### Headers

| Name          | Type   | Description             |
| ------------- | ------ | ----------------------- |
| Content-Type  | string | application/json        |
| Authorization | string | BWS authorization token |

#### Request Body

| Name        | Type   | Description                               |
| ----------- | ------ | ----------------------------------------- |
| catalogid   | number | After DID is created, add to this catalog |
| short\_name | string | A short name for this DID in this catalog |
| properties  | array  | Array of DID properties                   |

{% tabs %}
{% tab title="200 " %}

```
{
    "result": "success",
    "hash": "0x37052298c931f77da860fdf165611187bb89f76a3f2ee20abbf538836822a2f5",
    "block": "0x20fdb4a3e9ad6c1b0f609884b45a8622f6499f636ab2446d059655f7d9bf5b9b",
    "extrinsic": "0x5c15820bc6822ad8f90847a643257a036454b296d1168a779fbc872b489f056e",
    "created": "2020-02-05T10:22:30.020284"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Create with properties" %}

```
{	
	"short_name":"National Hawkers Foundation",
	"properties": [
    {
      "name": "Name",
      "private": true,
      "type": "Text",
      "value": "Atanu Roy"
    }
  ]
}
```

{% endtab %}

{% tab title="Add to a catalog" %}

```
{
  "catalogid": "1234",
  "short_name": "My DID", 	
	"properties": [
    {
      "name": "Name",
      "private": true,
      "type": "String",
      "value": "Atanu Roy"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

#### DID property&#x20;

A DID property is a JSON object composed of the following keys.

| Name    | Description                                                                           | Required |
| ------- | ------------------------------------------------------------------------------------- | -------- |
| name    | Name of the property                                                                  | Yes      |
| private | If true, this property is not stored on chain                                         | No       |
| type    | Value type of this property. Allowed values are **Text**, **Bool**, **Integer, Date** | Yes      |
| value   | Actual value to be stored                                                             | Yes      |

## Retrieve a DID

<mark style="color:blue;">`GET`</mark> `https://api.borlaug.network/identity/dids/:did`

Retrieve a DID with all its information

#### Query Parameters

| Name       | Type   | Description                                                         |
| ---------- | ------ | ------------------------------------------------------------------- |
| page       | string | Zero based pagenation of properties                                 |
| per\_page  | string | Items per page (properties)                                         |
| properties | string | Comma separated property names to retrieve selected properties only |

#### Headers

| Name          | Type   | Description             |
| ------------- | ------ | ----------------------- |
| Authorization | string | BWS authorization token |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Request Query" %}

```
GET /identity/dids/:did?properties=name,age,created_at
```

{% endtab %}
{% endtabs %}

```
GET /identity/dids/:did?page=0&per_page=10
```

## Retrieve DIDs for a given public key

<mark style="color:blue;">`GET`</mark> `https://api.borlaug.network/identity/dids?public_key=`

Retrieves all DIDs for a subject identified by the public\_key

#### Headers

| Name          | Type   | Description             |
| ------------- | ------ | ----------------------- |
| Authorization | string | BWS authorization token |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Modify a DID

<mark style="color:orange;">`PUT`</mark> `https://api.borlaug.network/identity/dids/:did`

Update a DID with given properties. This is an idempotent call. It replaces any properties associated with the DID with given array of properties.

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Content-Type   | string | application/json        |
| Authentication | string | BWS authorization token |

#### Request Body

| Name       | Type  | Description             |
| ---------- | ----- | ----------------------- |
| properties | array | array of DID properties |

{% tabs %}
{% tab title="200 " %}

```
{
    "result": "success",
    "hash": "0x37052298c931f77da860fdf165611187bb89f76a3f2ee20abbf538836822a2f5",
    "block": "0x20fdb4a3e9ad6c1b0f609884b45a8622f6499f636ab2446d059655f7d9bf5b9b",
    "extrinsic": "0x5c15820bc6822ad8f90847a643257a036454b296d1168a779fbc872b489f056e",
    "created": "2020-02-05T10:22:30.020284"
}
```

{% endtab %}
{% endtabs %}

Create a DID with some properties

{% tabs %}
{% tab title="Request Body" %}

```
{	
	"properties": [
    {
      "name": "Name",
      "private": true,
      "type": "String",
      "value": "Atanu Roy"
    },
    {
      "name": "Membership Status",
      "type": "Bool",
      "value": "true"
    }    
  ]
}
```

{% endtab %}
{% endtabs %}

## Add or remove properties of a DID

<mark style="color:purple;">`PATCH`</mark> `https://api.borlaug.network/identity/dids/:did`

#### Headers

| Name          | Type   | Description             |
| ------------- | ------ | ----------------------- |
| Content-Type  | string | application/json        |
| Authorization | string | BWS authorization token |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Sample Request" %}

```
{	
  "add": [
    {
      "name": "Name",
      "private": true,
      "type": "String",
      "value": "Atanu Roy"
    },
    {
      "name": "Membership Status",
      "type": "Bool",
      "value": "true"
    }    
  ],
  "remove": [
    {
      "name": "Weight",
    },
    {
      "name": "Age",
    }    
  ]  
}
```

{% endtab %}
{% endtabs %}

## Add or remove controllers

<mark style="color:purple;">`PATCH`</mark> `https://api.borlaug.network/identity/dids/:did/controllers`

Manage controllers for your DID\
\
**NOTE:** Subject can not remove itself from the controller list.

#### Headers

| Name          | Type   | Description             |
| ------------- | ------ | ----------------------- |
| Content-Type  | string | application/json        |
| Authorization | string | BWS authorization token |

#### Request Body

| Name   | Type  | Description               |
| ------ | ----- | ------------------------- |
| remove | array | Controller DIDs to remove |
| add    | array | Controller DIDs to add    |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Request Body" %}

```
{
  add: [],
  remove: []
}
```

{% endtab %}
{% endtabs %}