Identity Agent Guide

site/docs/web5/build/Agent/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Agents",
+  "position": 4
+}

site/docs/web5/build/Agent/how-to-create-identity-agent.mdx

@@ -0,0 +1,104 @@
+---
+sidebar_position: 1
+---
+# Create an identity agent
+
+Identity agents manage [Decentralized Identifiers (DIDs)](https://developer.tbd.website/docs/web5/learn/decentralized-identifiers), data, and communication between [Decentralized Web Nodes (DWNs)](https://developer.tbd.website/docs/web5/learn/decentralized-web-nodes). For developers' convenience, the `Web5.connect()` function uses default settings to connect to an identity agent. However, there can be scenarios where setting up a custom agent is necessary. This guide provides a step-by-step demonstration of how to create an identity agent equipped with a [portable DID](https://developer.tbd.website/docs/web5/build/decentralized-identifiers/how-to-create-did#portable-did).
+
+<details>
+<summary>Prerequisites</summary>
+
+**Install the following packages**
+
+```bash
+npm i @web5/dids @web5/user-agent @web5/api
+```
+
+**Import the following modules**
+```js
+import { DidIonMethod, DidKeyMethod } from '@web5/dids';
+import { Web5UserAgent } from '@web5/user-agent';
+import { Web5, getTechPreviewDwnEndpoints } from '@web5/api';
+```
+This guide focuses on utilizing `DidIonMethod` and `DidKeyMethod` for setting up an identity agent. Currently, DID methods like the `DidDhtMethod` are not supported in this context.
+</details>
+
+## Initialize the Agent
+Create an instance of the Web5 User Agent to begin your identity agent setup.
+```javascript
+const agent = await Web5UserAgent.create();
+```
+
+## Authenticate with a passphrase
+For security purposes, the identity agent prompts the end user to enter a secure passphrase when it initially launches. In this example, `insecure-static-phrase` is used as a placeholder.
+```javascript
+await agent.start({ passphrase: 'insecure-static-phrase' });
+```
+
+## Generate a portable DID
+Generating a portable DID document requires the following steps
+- **getTechPreviewDwnEndpoints()** - selects up to 2 DWN endpoints that are provided by default during the Tech Preview period.
+ * **DidIonMethod.generateDwnOptions({ serviceEndpointNodes })** - generates two key pairs used for authorization and encryption purposes when interfacing with DWNs. The IDs of these keys are referenced in the service object that includes the dwnUrls provided.
+ * **DidIonMethod.create(didOptions)** - creates the DID document with the given options
+```javascript
+const serviceEndpointNodes = await getTechPreviewDwnEndpoints();
+const didOptions = await DidIonMethod.generateDwnOptions({ serviceEndpointNodes });
+const portableDid = await DidIonMethod.create(didOptions);
+```
+<details>
+<summary>The above code snippet is the equivalent of:</summary>
+
+```javascript
+await DidIonMethod.create({
+        services: [{
+            type: 'DecentralizedWebNode',
+            id: '#dwn',
+            serviceEndpoint: {
+                "encryptionKeys": [
+                    "#dwn-enc"
+                ],
+                "nodes": [
+                    "https://dwn.tbddev.org/dwn0",
+                    "https://dwn.tbddev.org/dwn2"
+                ],
+                "signingKeys": [
+                    "#dwn-sig"
+                ]
+            }
+        }]
+    })
+```
+</details>
+
+## Import your portable DID
+Importing your portable DID, gives the identity agent permission to manage data on your behalf. This step links your agent you your unique decentralized identifier (DID).
+
+```js
+await agent.didManager.import({
+    did: portableDid,
+    kms: "local"
+});
+```
+
+:::note
+The KMS field stands for Key Management Store. It acts as a password manager for cryptographic keys. If you don't specify a particular key management service, such as AWS Key Management Service or Google Cloud Key Management, it will default to Web5's default implementation
+:::
+
+## Connect to Web5
+Now, you can take portable DID and your identity agent to connect to Web5 and return an instance of Web5.
+```javascript
+    const { web5, did } = await Web5.connect({
+        connectedDid: portableDid.did,
+        agent,
+    });
+```
+
+## Interact with the Web5 API
+You can now use the web5 instance to interact with DWNs and store Verifiable Credentials. The example below demonstrates how to create a record with a simple "Hello World!" message:
+```javascript
+    const { record } = await web5.dwn.records.create({
+        data: "Hello World!",
+        message: { dataFormat: "text/plain" },
+    });
+
+```

site/docs/web5/build/apps/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Apps",
-  "position": 4
+  "position": 5
 }