Some improvements in the Biotz academy developer-api docs

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.
-
-
-
-
-
-
-

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