From db2e1fdf0ba3498b754129e505b1604f1d3b3fbe Mon Sep 17 00:00:00 2001
From: darssy <13643651+darssy@users.noreply.github.com>
Date: Mon, 18 Mar 2024 14:07:02 +0100
Subject: [PATCH] Added a use case of secure API token in YML

---
 src/docs/api/index.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/src/docs/api/index.md b/src/docs/api/index.md
index b759c5c05..ee9e06810 100644
--- a/src/docs/api/index.md
+++ b/src/docs/api/index.md
@@ -42,6 +42,22 @@ $headers["Content-type"] = "application/json"
 Invoke-RestMethod -Uri 'https://ci.appveyor.com/api/roles' -Headers $headers -Method Get
 ```
 
+### YML
+Your API token needs to be stored in a [secure variable](/docs/build-configuration/#secure-variables) before appearing in a `yml` file. You can store it in an environment variable for that purpose. As a result the above PowerShell snippet will be written in a yml file as follows:
+
+```yml
+environment:
+  api_token:
+    secure: <your-secure-api-token>
+before_build: #just an example
+    - ps: |
+        $token = $env:api_token
+        $headers = @{}
+        $headers['Authorization'] = "Bearer $token"
+        $headers["Content-type"] = "application/json"
+        Invoke-RestMethod -Uri 'https://ci.appveyor.com/api/roles' -Headers $headers -Method Get
+```
+
 <!-- markdownlint-disable MD003 MD022 -->
 ### C\#
 <!-- markdownlint-enable MD003 MD022 -->