From 5073b6d4dc2bdaa760961f1b47d29232fe082c94 Mon Sep 17 00:00:00 2001
From: Aleix Quintana Alsius <kinta@communia.org>
Date: Fri, 21 Apr 2023 12:20:51 +0000
Subject: [PATCH] translate integrations

---
 docs/integrations.md | 63 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 docs/integrations.md

diff --git a/docs/integrations.md b/docs/integrations.md
new file mode 100644
index 0000000..a6fdce2
--- /dev/null
+++ b/docs/integrations.md
@@ -0,0 +1,63 @@
+# Integrations
+
+The dd can be integrated with other systems using their APIs.
+
+## Autentication
+
+All requests must be authenticated with a [Json Web Token (JWT)][jwt],
+and must be signed with the `API_SECRET` (defined in `dd.conf`).
+
+This authentication is done with the `Authentication` http header.
+
+<details>
+<summary>Read details</summary>
+```sh
+> curl -H "Authorization: bearer ${jwt}" https://admin.DOMAIN/ddapi/roles
+[
+  {
+    "keycloak_id": "9325ad99-7e04-4c31-9768-5512e1564160",
+    "id": "admin",
+    "name": "admin",
+    "description": "${role_admin}"
+  },
+  {
+    "keycloak_id": "c6c8a73e-51fc-4716-831d-1dfc0e0b62b0",
+    "id": "manager",
+    "name": "manager",
+    "description": "Realm managers"
+  },
+  {
+    "keycloak_id": "24d7977e-da83-4591-8e13-0fac3126afa1",
+    "id": "student",
+    "name": "student",
+    "description": "Realm students"
+  },
+  {
+    "keycloak_id": "d6699c41-13d5-4623-bdca-e5f2775474ed",
+    "id": "teacher",
+    "name": "teacher",
+    "description": "Realm teachers"
+  }
+]
+```
+
+Where <code>JWT</code> can be generated, e.g. using <code>python-jose</code>:
+
+```python
+import os
+from jose import jws
+t = jws.sign({}, os.environ["API_SECRET"], algorithm="HS256")
+print(t)
+```
+
+Other programming languages have similar ways of generating tokens.
+</details>
+
+[jwt]: https://jwt.io/
+[jose]: https://python-jose.readthedocs.io/
+
+## API Notable
+
+![Projecte NotaBLE](assets/images/notable.jpg)
+
+!!swagger ddapi.json!!