GITBOOK-8665: API: Create one how to authenticate page using Authenti…

…cation for API

docs/snyk-api/rest-api/authentication-for-api/README.md

@@ -1,22 +1,48 @@
 # Authentication for API
 
-This section provides information about how to [Authenticate for the API](authenticate-for-the-api.md), including obtaining your API token and using it in the authentication header, and [Snyk API token permissions users can control](snyk-api-token-permissions-users-can-control.md).
+To use the Snyk API, you must be an Enterprise plan customer and have a token from Snyk.
 
-For instructions on obtaining a new API token, see [Revoke and regenerate a Snyk API token](revoke-and-regenerate-a-snyk-api-token.md).
-
-The following explains **when to use an API token** and **when to use a service account token**.
-
-Your Snyk API token is a personal token available under your user profile. The Snyk API token is associated with your Snyk Account and not with a specific Organization.
-
-Free and Team plan and trial users have access to only this personal token. The personal token can be used to authenticate with the Snyk CLI running on a local or a build machine and an IDE when you are setting a token manually. Use a personal token with caution if you are authenticating with the API or for CI/CD.
-
-Enterprise users have access to a personal token under their profile and to service account tokens. For details, see [Service accounts](../../../enterprise-setup/service-accounts/).
+Enterprise users have [access to a personal token under their profile](./#how-to-obtain-your-personal-token) and to service account tokens. The personal API token is associated with your Snyk Account and not with a specific Organization. For more information, see [Service accounts](../../../enterprise-setup/service-accounts/).
 
 * **Enterprise users should use a service account** to authenticate for any kind of automation. This includes, but is not limited to, CI/CD scanning with the CLI or build system plugins and any automation, including automation with the API.
 * **Enterprise users should use the personal token** under their user profile for:
-  * Running the CLI locally on their machine
+  * Running the CLI locally on their machine; for details, see [Authenticate to use the CLI](../../../snyk-cli/authenticate-to-use-the-cli.md).
   * Authenticating with the IDE manually
   * Running API calls one time, for example, to test something
 
-For more information on the personal Snyk API token, see [Authenticate for the API](authenticate-for-the-api.md) and  [Authenticate to use the CLI](../../../snyk-cli/authenticate-to-use-the-cli.md).
+For more information, see [Snyk API token permissions users can control](snyk-api-token-permissions-users-can-control.md).
+
+## How to obtain your personal token
+
+You can find your personal API token in your personal [General Account Settings](https://app.snyk.io/account) after you register with Snyk and log in. In the **key** field, **Click to show**. Then, highlight and copy the API key.
+
+If you want a new API token, select **Revoke & Regenerate.** This will make the previous API token invalid. For details, see [Revoke and regenerate a Snyk API token](revoke-and-regenerate-a-snyk-api-token.md).
+
+## How to use a Snyk API token
+
+When using the API directly, provide the API token in an `Authorization` header, as in the following example request, replacing `API_TOKEN` with your token
+
+```bash
+curl --request GET \
+--url "https://api.snyk.io/rest/self?version=2024-06-10" \
+--header "Content-Type: application/vnd.api+json" \
+--header "Authorization: token API_TOKEN"
+```
+
+If you are using the API through [Snyk Apps](../../how-to-use-snyk-apps-apis/), provide the `access_token` in an `Authorization` header preceded by `bearer` as follows:
+
+```
+Authorization: bearer ACCESS_TOKEN
+```
+
+Otherwise, a `401 Unauthorized` response will be returned:
+
+```http
+HTTP/1.1 401 Unauthorized
+
+{
+    "status": "401",
+    "code": "Unauthorized"
+}
+```
 

docs/snyk-api/rest-api/authentication-for-api/authenticate-for-the-api.md

@@ -1,33 +1,3 @@
 # Authenticate for the API
 
-To use the Snyk API, you must get your API token from Snyk. You can find your token in your personal [General Account Settings](https://app.snyk.io/account) after you register with Snyk and log in. In the **key** field, **Click to show**. Then, highlight and copy the API key.
-
-If you want a new API token, select **Revoke & Regenerate.** This will make the previous API token invalid. For details, see [Revoke and regenerate a Snyk API token](revoke-and-regenerate-a-snyk-api-token.md).
-
-When using the API directly, provide the API token in an `Authorization` header, as in the following example request, replacing `API_TOKEN` with your API Token
-
-```bash
-curl --request GET \
---url "https://api.snyk.io/rest/self?version=2024-06-10" \
---header "Content-Type: application/vnd.api+json" \
---header "Authorization: token API_TOKEN"
-```
-
-If you are using the API through [Snyk Apps](../../how-to-use-snyk-apps-apis/), provide the `access_token` in an `Authorization` header preceded by `bearer` as follows:
-
-```
-Authorization: bearer ACCESS_TOKEN
-```
-
-Otherwise, a `401 Unauthorized` response will be returned:
-
-```http
-HTTP/1.1 401 Unauthorized
-
-{
-    "status": "401",
-    "code": "Unauthorized"
-}
-```
-
-For information on when to use an API token and when to use a service account token, see [Authentication for API](./).
+See [Authentication for API](./).

docs/snyk-cli/authenticate-to-use-the-cli.md

@@ -64,7 +64,7 @@ All subsequent test calls will be authenticated automatically.  For more informa
 
 ## How to authenticate to use the CLI in CI/CD pipelines
 
-**Free and Team plan users** are more likely to **use this method in a CI/CD pipeline** than to use OAuth 2.0. **Enterprise plan customers** are advised to use a [**service account**](../enterprise-setup/service-accounts/) in a CI/CD pipeline. For detailes about when to use an API token and when to use a service account token, see [Authentication for API](../snyk-api/rest-api/authentication-for-api/).
+**Free and Team plan users** are more likely to **use this method in a CI/CD pipeline** than to use OAuth 2.0. **Enterprise plan customers** are advised to use a [**service account**](../enterprise-setup/service-accounts/) in a CI/CD pipeline. For details about when to use an API token and when to use a service account token, see [Authentication for API](../snyk-api/rest-api/authentication-for-api/).
 
 All CLI `test` commands can automatically recognize the environment variable `SNYK_TOKEN` and use it for authentication. For details, see [Environment variables for Snyk CLI](configure-the-snyk-cli/environment-variables-for-snyk-cli.md).