Update documentation

Signed-off-by: Kirill.Sybin <[email protected]>

docs/_docs/integrations/badges.md

@@ -5,14 +5,21 @@ chapter: 6
 order: 10
 ---
 
-Dependency-Track supports badges in Scalable Vector Graphics (SVG) format. Support for badges is a globally configurable
-option and is disabled by default.
+Dependency-Track supports badges in Scalable Vector Graphics (SVG) format. Support for badges is configurable on a team
+basis via permission. 
 
-> Enabling badge support will provide vulnerability and policy violation metric information to unauthenticated users.
-> Any anonymous user with network access to Dependency-Track and knowledge of a projects information will be able
-> to view the SVG badge.
+To enable badges for a team, activate the permission `VIEW_BADGES`. To deactivate badges, remove the permission. To 
+retrieve a badge, use a team's API key either in the badge API header `X-API-Key` or in the URI parameter `apiKey`.
 
-In all following examples, replace `{name}`, `{version}`, and `{uuid}` with their respective values.
+> As badges are typically embedded in places that more people have access to than to Dependency-Track, the API key used
+> for the badge request should have minimal scope to prevent unintended access beyond that badge. Ideally, the API
+> key belongs to a single-purpose team, having just the `VIEW_BADGES` permission, with only one API key and access to 
+> only the projects/project versions whose badges are displayed at one site--the latter requiring _Portfolio Access 
+> Control_. 
+
+In all following examples, replace `{name}`, `{version}`, `{uuid}`, and `{apiKey}` with their respective values. For
+brevity, the examples use the URI query parameter as the method of authentication, however, they also work with
+authentication by header.
 
 ### Vulnerable components
 Create a badge for vulnerable components of the project. It either shows:
@@ -33,8 +40,8 @@ name and version.
 
 #### Examples
 ```
-https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}
-https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}
+https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}?apiKey={apiKey}
+https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}?apiKey={apiKey}
 ```
 
 ### Policy violations
@@ -57,8 +64,8 @@ projects name and version.
 #### Examples
 
 ```
-https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}
-https://dtrack.example.com/api/v1/badge/violations/project/{uuid}
+https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}?apiKey={apiKey}
+https://dtrack.example.com/api/v1/badge/violations/project/{uuid}?apiKey={apiKey}
 ```
 
 
@@ -67,17 +74,17 @@ You can embed the badges in other documents. It allows you to display a badge in
 
 #### HTML Examples
 ```html
-<img src="https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}">
-<img src="https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}">
-<img src="https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}">
-<img src="https://dtrack.example.com/api/v1/badge/violations/project/{uuid}">
+<img src="https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}?apiKey={apiKey}">
+<img src="https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}?apiKey={apiKey}">
+<img src="https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}?apiKey={apiKey}">
+<img src="https://dtrack.example.com/api/v1/badge/violations/project/{uuid}?apiKey={apiKey}">
 ```
 
 #### Markdown Examples
 ```markdown
-![alt text](https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version})
-![alt text](https://dtrack.example.com/api/v1/badge/vulns/project/{uuid})
-![alt text](https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version})
-![alt text](https://dtrack.example.com/api/v1/badge/violations/project/{uuid})
+![alt text](https://dtrack.example.com/api/v1/badge/vulns/project/{name}/{version}?apiKey={apiKey})
+![alt text](https://dtrack.example.com/api/v1/badge/vulns/project/{uuid}?apiKey={apiKey})
+![alt text](https://dtrack.example.com/api/v1/badge/violations/project/{name}/{version}?apiKey={apiKey})
+![alt text](https://dtrack.example.com/api/v1/badge/violations/project/{uuid}?apiKey={apiKey})
 ```