@tk what you are asking it is not very clear.

we had to allow additional capabilities in apache vhost configuration that are locked down due to safety reasons in general

If the use of .htaccess is a problem for you and do not want to enable it, you simply need to add the necessary directives to your Apache vhost / directory configuration as appropriate, there is no obligation to allow overrides.

If you want the documentation to be updated, then it would be useful to provide us additional context and details, i.e. the actual errors that you got, and what needs to be changed to fix it (the vhost config you posted possibly includes additional directives that are not necessary to address the problem).

Providing the text you would like to see added would be nice too, keeping in mind that it needs to be generic so it remains applicable for other environments.

@dregard : hope to get the point more clearly:

• Prerequisite: mantis before 2.25.8, apache 2.4.13+
• Problem: After update to mantis 2.25.8 or above, all REST API calls return error 500:

  
  
  500 Internal Server Error

Internal Server Error
The server encountered an internal error or misconfiguration and was unable to complete your request.

and the apache error log shows entries:

... [mantis_base]/api/rest/.htaccess: CGIPassAuth not allowed here

• Cause of problem: In mantis-2.25.8 the directive "CGIPassAuth On" has been added in api/rest/.htaccess . Application of this directive will be denied if the required contextual permissions are not granted in the apache vhost configuration
• Solution: The complete block of directives must be added to apache vhost configuration:

  
  
  <Directory "[mantis_base]/api/rest/">
  
  AllowOverride AuthConfig FileInfo
  
  Options FollowSymLinks
  
  Require all granted
  
  </Directory>

• Notes:
  Options FollowSymlinks is required, otherwise apache throws error "Options FollowSymLinks and SymLinksIfOwnerMatch are both off, so the RewriteRule directive is also forbidden due to its similar ability to circumvent directory restrictions ". The rewrite is another part of [mantis_base]/api/rest/.htaccess .
  Regarding "Require all granted" cf. https://webmasters.stackexchange.com/questions/107049/what-does-require-all-granted-on-directory-root-realy-means-apache-2-4-o or https://htaccessbook.com/access-control-apache-2-4/

Thanks for the detailed explanation, now I understand better.