diff --git a/scm-webapp/src/main/doc/openapi.md b/scm-webapp/src/main/doc/openapi.md
index bf565699d4..4f5fa57955 100644
--- a/scm-webapp/src/main/doc/openapi.md
+++ b/scm-webapp/src/main/doc/openapi.md
@@ -1,7 +1,7 @@
 The following REST documentation describes all public endpoints of your SCM-Manager instance. 
 You can try the endpoints with or without authentication right on the swagger surface provided by the OpenAPI-Plugin.
 
-For authenticated requests please use the "Authorize" button and insert your preferred authentication method. 
+For authenticated requests please login to the SCM-Manager. You can also use the "Authorize" button and insert your preferred authentication method. 
 For basic authentication simply use your SCM-Manager credentials. If you want to use the bearer token authentication, you can generate an 
 valid token using the authentication endpoint and copy the response body.
 
@@ -10,6 +10,6 @@ Using the HATEOAS architecture for REST allows us to provide discoverable and se
 The responses are build using the [HAL JSON format](http://stateless.co/hal_specification.html). 
 HAL makes the API human-friendly and simplifies the communication between the frontend and the server using links and embedded resources.
 
-We highly suggest using HAL links when creating new functions for SCM-Manager since they are consistent and can be
-permission checked before being append to the response. The links and embedded resources can also be used by plugins, which can
+We highly suggest using HAL links when creating new functions for SCM-Manager since they are consistent and are only 
+appended to the response when user has the necessary permissions. The links and embedded resources can also be used by plugins, which can
 define new resources or enrich existing ones.