# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.borlaug.services/api/identity/dids.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.