From f7e7ffeb3f2533e1664bc7ba49cb32cddb3bbda8 Mon Sep 17 00:00:00 2001
From: Bingen Galartza Iparragirre <bingen.galartza@biotz.io>
Date: Tue, 27 Aug 2024 18:34:05 +0200
Subject: [PATCH] Some improvements in the Biotz academy developer-api docs

---
 ...How to create developer API credentials.md |  9 +--
 docs/Reference guides/Developer API.md        | 16 ------
 docs/Reference guides/developer-api.md        | 57 +++++++++++++++++++
 3 files changed, 58 insertions(+), 24 deletions(-)
 delete mode 100644 docs/Reference guides/Developer API.md
 create mode 100644 docs/Reference guides/developer-api.md

diff --git a/docs/How-to guides/How to create developer API credentials.md b/docs/How-to guides/How to create developer API credentials.md
index 7845688..9233656 100644
--- a/docs/How-to guides/How to create developer API credentials.md	
+++ b/docs/How-to guides/How to create developer API credentials.md	
@@ -36,7 +36,7 @@ Now that we have our credentials created. We need to configure the authenticatio
 ![Developer](img/biotz-developer-api.png)
 </div>
 Clicking the **Authorize** button a pop-up will show, in which we need to add this information, also found on the
-<a href="/docs/Reference guides/Developer API" target="_self">Developer API Reference</a>.
+<a href="/docs/Reference guides/developer-api" target="_self">Developer API Reference</a>.
 
 - **Username:** The username in the credentials file we have downloaded before.
 - **Password:** The password in the credentials file we have downloaded before.
@@ -54,10 +54,3 @@ When the authorization is done correctly, you should see a pop-up saying that yo
 ![authorize2](img/authorize-2.png)
 </div>
 With this your capable of consuming the API and get the needed data.
-
-
-
-
-
-
-
diff --git a/docs/Reference guides/Developer API.md b/docs/Reference guides/Developer API.md
deleted file mode 100644
index 172f851..0000000
--- a/docs/Reference guides/Developer API.md	
+++ /dev/null
@@ -1,16 +0,0 @@
----
-sidebar_position: 4
----
-
-# Developer API
-
-Here you can see the different data related to the developer API.
-
-# Reference data
-The API documentation with every available endpoint is [here](https://api.biotz.io/docs/ui/index.html#/). If you want to know how to authorize correctly before consuming the API go <a href="/docs/How-to guides/How to create developer API credentials" target="_self">here</a>.
-
-In order to connect correctly you'll need this data:
-
-- **Authentication Token URL**: https://auth.biotz.io/realms/biotz-platform/protocol/openid-connect/token
-- **Client_id**: biotz-platform-programmatic-users
-- **Scope**: openid
diff --git a/docs/Reference guides/developer-api.md b/docs/Reference guides/developer-api.md
new file mode 100644
index 0000000..d2eb175
--- /dev/null
+++ b/docs/Reference guides/developer-api.md	
@@ -0,0 +1,57 @@
+---
+title: Developer API
+description: Developer API reference
+sidebar_position: 4
+---
+
+# Developer API
+
+You can interact with the Biotz platform using the Developer API.
+
+### API reference
+
+The API is documented in the [OpenAPI][] v3.0 format. You can browse the
+reference using [Biotz's Swagger][].
+
+
+### Authentication
+
+The Biotz Developer API uses OpenID JWT id-tokens for
+authentication.
+
+#### Obtaining Developer API Credentials
+
+Developer API credentials are required for obtaining tokens. The
+credentials can be created in the "Developer API" section of the Biotz
+web application.
+
+:::warning
+
+Make sure to save the Developer API credentials in a safe place.
+
+:::
+
+#### Obtaining an identity token
+
+The token can be obtained using the [OpenAuth Password Grant flow][]:
+
+- **Token URL**: https://auth.biotz.io/realms/biotz-platform/protocol/openid-connect/token
+- **Request parameters**:
+  - `grant_type`: `"password"`
+  - `client_id`: `"biotz-platform-programmatic-users"`
+  - `scope`: `"openid"`
+  - `username`: Developer API credentials username.
+  - `password`: Developer API credentials password.
+
+#### Using the obtained token
+
+The id token has to be sent in every API request using the [HTTP Authorization request header][].
+
+``` http
+Authorization: Bearer <id-token>
+```
+
+[OpenAuth Password Grant Flow]: https://www.oauth.com/oauth2-servers/access-tokens/password-grant/
+[OpenAPI]: https://swagger.io/resources/open-api/
+[Biotz's Swagger]: https://api.biotz.io/docs/ui/index.html#/
+[HTTP Authorization request header]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization