dta details
diff --git a/docs/dta-details/authentication.md b/docs/dta-details/authentication.md
new file mode 100644
index 0000000..2c25830
--- /dev/null
+++ b/docs/dta-details/authentication.md
@@ -0,0 +1,18 @@
+---
+id: authentication
+title: Authentication
+sidebar_label: Authentication
+---
+Milagro DTA's endpoints are "in the clear" by default but if you set these flags you can have the endpoints authenticate against your oAuth provider of choice.
+
+This will secure the REST API endpoints /identity and /order
+
+The RPC endpoints /fulfill are protected using the Milagro communicatio protocol (oAuth is not required)
+
+```
+config.yaml
+
+oidc_provider: URL for oAuth endpoint
+oidc_client_id: _your server secret_
+
+```
\ No newline at end of file
diff --git a/docs/dta-details/identity-documents.md b/docs/dta-details/identity-documents.md
new file mode 100644
index 0000000..bcbdbdb
--- /dev/null
+++ b/docs/dta-details/identity-documents.md
@@ -0,0 +1,36 @@
+---
+id: identity-documents
+title: Identity Documents
+sidebar_label: Identity Documents
+---
+The first problem that Milagro-DTA aims to solve is how actors in the system can identify and trust each other. In order to participate in the Milagro DTA safeguarding process each actor must publish a set of public keys into IPFS. The IPFS hash for an identity documents is then the ID for each actor.
+
+In order to create an identity document Milagro DTA provides the following endpoint.
+
+[POST: /identity](http://localhost:3000/swagger/index.html#/identity/createIdentity)
+
+The document contains public keys for signing and key encapsulation. The Milagro DTA communication protocol uses protbufs for serialisation, the defitnition of an identity document is:
+```
+message IDDocument {
+ string AuthenticationReference = 2 ;
+ bytes SikePublicKey = 3 ;
+ bytes PicnicPublicKey = 4 ;
+ string Handle = 5 ;
+ string Email = 6 ;
+ string Username = 7 ;
+ int64 Timestamp = 8;
+}
+```
+Authentication reference refers to Milagro's out of the box oAuth integration
+
+The node that is used to create an identity document will store the seed and secret keys associated with the Identity. In RC1 these are store as a JSON file in the key value store:
+
+```
+//IdentitySecrets - keys required for decryption and signing
+type IdentitySecrets struct {
+ Name string `json:"name"`
+ Seed string `json:"seed"`
+ SikeSecretKey string `json:"sikeSecretKey"`
+ PicnicSecretKey string `json:"picnicSecretKey"`
+}
+```
\ No newline at end of file
diff --git a/docs/dta-details/why-ipfs.md b/docs/dta-details/why-ipfs.md
new file mode 100644
index 0000000..abd5d74
--- /dev/null
+++ b/docs/dta-details/why-ipfs.md
@@ -0,0 +1,7 @@
+---
+id: why-ipfs
+title: Why IPFS?
+sidebar_label: Why IPFS?
+---
+
+Milagro DTA aims to provide and auditable record of all interactions between actors in the system. Whenever a secret is created or redeemed an imutable, secure and attributrable record is kep. It is vital that all the actors in the system can refer to an agreed record of these transactions incase of dispute or inresponse to requests from third parties such as law enforcement or audit / compl
\ No newline at end of file
