GITBOOK-7295: API: tweaks to main page, REST API through Authenticati…

…on, V1 API, OAuth2 API

docs/SUMMARY.md

@@ -965,7 +965,6 @@
     * [Users (v1)](snyk-api/reference/users-v1.md)
     * [Users](snyk-api/reference/users.md)
     * [Webhooks (v1)](snyk-api/reference/webhooks-v1.md)
-  * [API endpoints index and notes](snyk-api/api-endpoints-index-and-notes.md)
   * [Snyk Apps](snyk-api-info/snyk-apps/README.md)
     * [Prerequisites for Snyk Apps](snyk-api/snyk-apps/prerequisites-for-snyk-apps.md)
     * [Scopes to request](snyk-api/snyk-apps/scopes-to-request.md)
@@ -1020,6 +1019,7 @@
       * [Contributing to snyk-api-import](snyk-api/snyk-tools/tool-snyk-api-import/contributing.md)
     * [Tool: jira-tickets-for-new-vulns](snyk-api/snyk-tools/tool-jira-tickets-for-new-vulns.md)
     * [Python code to extract issues from Snyk API](snyk-api/snyk-tools/python-code-to-extract-issues-from-snyk-api.md)
+  * [API endpoints index and notes](snyk-api/api-endpoints-index-and-notes.md)
   * [Make calls to the Snyk API](snyk-api/make-calls-to-the-snyk-api/README.md)
     * [Try a simple call to the Snyk REST API](snyk-api/make-calls-to-the-snyk-api/try-a-simple-call-to-the-snyk-rest-api.md)
     * [Find the differences between versions in the REST API](snyk-api/make-calls-to-the-snyk-api/find-the-differences-between-versions-in-the-rest-api.md)

docs/getting-started/how-to-obtain-and-authenticate-with-your-snyk-api-token.md

@@ -4,9 +4,9 @@ Your Snyk API token is a personal token available under your user profile. A tok
 
 Free, Team, and Trial plan users have access only to this personal token under the user profile. The **personal token can be used** to authenticate with:
 
-* A CI/CD integration
 * The Snyk CLI running on a local or a build machine
 * An IDE, when setting a token manually
+* A CI/CD integration
 
 Enterprise users have access to a personal token under their profile and to service account tokens. For details, see [Service accounts](../enterprise-configuration/service-accounts/).
 
@@ -26,7 +26,7 @@ Follow these steps to obtain your personal Snyk API token:
 
 1. Log in to Snyk and navigate to your **Account settings**
 2. In the **Account Settings,** select **General** > **Auth Token**
-3. Click inside the **KEY** box to display your API token.
+3. In the KEY field, **click to show** and then select and copy your API token.
 4. Copy the token and save it in a secure location for future use.
 
 <figure><img src="../.gitbook/assets/Snyk Broker - API Token - Account settings - API Token box.png" alt="Settings page, display API token"><figcaption><p>Settings page, display API token</p></figcaption></figure>

docs/snyk-api/README.md

@@ -12,7 +12,7 @@ Snyk [extensibility and the Snyk API](https://snyk.io/blog/extensibility-and-the
 
 ## Snyk REST API
 
-The [Snyk REST API](https://apidocs.snyk.io/) is based on the OpenAPI and JSON:API standards and represents an evolutionary approach to API development, with each endpoint versioned. For more information, see [Versioning](https://apidocs.snyk.io/#overview) in the reference docs. The most recent version of the REST API endpoints is also available in the [Reference](reference/) in the Snyk user docs along with the current [REST API overview](snyk-rest-api-overview/).
+The [Snyk REST API](https://apidocs.snyk.io/) is based on the OpenAPI and JSON:API standards and represents an evolutionary approach to API development, with each endpoint versioned. For more information, see [Versioning](https://apidocs.snyk.io/#overview) in the reference docs. The most recent version of the REST API endpoints is also available in the [Reference](reference/) in the Snyk user docs, along with the current [REST API overview](snyk-rest-api-overview/).
 
 ## Snyk V1 API (superseded by the REST API)
 
@@ -27,7 +27,7 @@ The [Snyk V1 API ](v1-api-overview/)has the ability to test a package for issues
 * Receiving remediation advice
 * Viewing user data to build custom security solutions
 
-The V1 API endpoints are available in the [Reference](reference/) in the Snyk user docs. Updates are made here. The endpoints migrated to the user docs remain [online](https://snyk.docs.apiary.io) also.
+The V1 API endpoints are available in the [Reference](reference/) in the Snyk user docs. Updates are made in the user docs. The endpoints migrated to the user docs remain [online](https://snyk.docs.apiary.io) also.
 
 ## When to use the API versus the CLI or an integration
 

docs/snyk-api/oauth2-api.md

@@ -1,8 +1,8 @@
 # OAuth2 API
 
-Snyk provides an OAuth2 API, primarily for use with [snyk-apps](../snyk-api-info/snyk-apps/ "mention"). It is compliment with RFC 6749.
+Snyk provides an OAuth2 API, primarily for use with [Snyk Apps](../snyk-api-info/snyk-apps/). It complies with RFC 6749.
 
-Most endpoints are served from our API subdomain (eg https://api.snyk.io) with the one exception being `/oauth2/authorize` which is served on the main app subdomain (eg https://app.snyk.io.)
+Most endpoints are served from the Snyk API subdomain (for example, https://api.snyk.io), with the one exception being `/oauth2/authorize` which is served on the main app subdomain (for example, https://app.snyk.io).
 
 {% swagger src="../.gitbook/assets/oauth-app-spec.yaml" path="/oauth2/authorize" method="get" %}
 [oauth-app-spec.yaml](../.gitbook/assets/oauth-app-spec.yaml)

docs/snyk-api/snyk-rest-api-overview/README.md

@@ -1,4 +1,4 @@
-# REST API overview
+# REST API
 
 {% hint style="info" %}
 The information on this page is also available in the [Snyk REST API reference docs](https://apidocs.snyk.io/).
@@ -8,7 +8,7 @@ Snyk REST API is based on the [JSON:API standard](https://jsonapi.org/), defined
 
 ## When to use Snyk REST API
 
-Use this API when you find endpoints that correspond to your needs according to your own workflow. You can also use Snyk API v1 at [https://snyk.docs.apiary.io/](https://snyk.docs.apiary.io/).
+Use this API when you find endpoints that correspond to your needs according to your own workflow. You can also use V1 API at [https://snyk.docs.apiary.io/](https://snyk.docs.apiary.io/).
 
 For more information about Snyk APIs and using an API versus Snyk CLI or an integration, see the [Snyk API docs](https://docs.snyk.io/snyk-api-info).
 
@@ -20,21 +20,21 @@ This API is only available over HTTPS. Accessing over HTTP will yield a 404 for
 
 ## About authentication
 
-To use this API, you must get your API token from Snyk. You can find your token in your General Account Settings on [https://snyk.io/account/](https://snyk.io/account/) after you register with Snyk and log in. See [Authentication for API](https://docs.snyk.io/snyk-api-info/authentication-for-api).
+To use this API, you must get your API token from Snyk. You can find your token in your General Account Settings [https://snyk.io/account/](https://snyk.io/account/) after you register with Snyk and log in. See [Authentication for API](https://docs.snyk.io/snyk-api-info/authentication-for-api).
 
 When using the API directly, provide the API token in an `Authorization` header, preceded by `token` exactly as follows (no initial capital letter or quotation marks):
 
 ```
 Authorization: token API_KEY
 ```
 
-If you are using the API through [Snyk Apps](https://docs.snyk.io/integrations/snyk-apps), provide the `access_token` in an `Authorization` header preceded by `bearer` as follows:
+If you are using the API through [Snyk Apps](https://docs.snyk.io/snyk-api/snyk-apps), 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:
+Otherwise, a 401 "Unauthorized" response will be returned:
 
 ```
 HTTP/1.1 401 Unauthorized
@@ -108,7 +108,7 @@ Sunset: Wed, 11 Nov 2021 11:11:11 GMT
 
 ## Pagination
 
-All endpoints in the Snyk REST API are paginated using _cursor-based_ pagination. This form of pagination helps prevent inconsistent results when collections are modified while they are being iterated. However, cursor-based pagination does not totally prevent inconsistent results, which can occur, for example, if an item is inserted in a prior page based on the sort order requested after a request is made. To mitigate the possibility of inconsistent results, by default Snyk sorts by insertion order so it is not possible to have items inserted on a prior page. However, if you specify the `sort` parameter, consistent pagination is no longer guaranteed. If you see inconsistent results you can submit a new request. If consistent pagination is important to your workflow, use the default insertion sort order.
+All endpoints in the Snyk REST API are paginated using _cursor-based_ pagination. This form of pagination helps prevent inconsistent results when collections are modified while they are being iterated. However, cursor-based pagination does not totally prevent inconsistent results, which can occur, for example, if an item is inserted in a prior page based on the sort order requested after a request is made. To mitigate the possibility of inconsistent results, by default, Snyk sorts by insertion order so it is not possible to have items inserted on a prior page. However, if you specify the `sort` parameter, consistent pagination is no longer guaranteed. If you see inconsistent results, you can submit a new request. If consistent pagination is important to your workflow, use the default insertion sort order.
 
 Whenever you receive an API response, it will contain appropriate links in the body of the response as follows:
 

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

@@ -3,12 +3,10 @@
 To use the Snyk API, you must first get your API token from Snyk.
 
 1. Go to the **General Account Settings** in [your Snyk account](https://app.snyk.io/account).
-2. In the KEY field, **click to show** and then select and copy your API token. Refer to the screenshot that follows.
+2. In the KEY field, **click to show** and then select and copy your API token.
 3. To use the Snyk API, supply the token in an `Authorization` header, preceded by `Token`:\
    `Authorization: Token API_KEY`
 
-For more information about authentication, refer to the overview in the [API reference docs](https://apidocs.snyk.io/). For additional information, see [Revoking and regenerating Snyk API tokens](revoking-and-regenerating-snyk-api-tokens.md).
+For more details and for information about using personal tokens versus service account tokens, see [How to obtain and authenticate with your Snyk API token](../../../getting-started/how-to-obtain-and-authenticate-with-your-snyk-api-token.md).
 
-![Get API token](<../../../.gitbook/assets/uuid-8d94edf8-b42b-e5b3-ada1-e157d18ff884-en (1) (1) (1) (1) (1) (1) (1) (1) (1) (1) (1) (1) (1) (1) (3) (16).png>)
-
-For information about using personal tokens versus service account tokens, see [How to obtain and authenticate with your Snyk API token](../../../getting-started/how-to-obtain-and-authenticate-with-your-snyk-api-token.md).
+For information about using the token, refer to [About authentication](https://docs.snyk.io/snyk-api/snyk-rest-api-overview#about-authentication) in the REST API overview. For additional information, see [Revoking and regenerating Snyk API tokens](revoking-and-regenerating-snyk-api-tokens.md).

docs/snyk-api/snyk-rest-api-overview/authentication-for-api/api-token-permissions-users-can-control.md

@@ -1,7 +1,7 @@
 # Snyk API token permissions users can control
 
-To set an API token to be read-only and unable to write to the platform, use a service account and set it to Group Viewer. **Note:** The [Get group audit logs endpoint](https://snyk.docs.apiary.io/#reference/audit-logs/group-level-audit-logs/get-group-level-audit-logs) requires Group Admin permissions.
+To set an API token to be read-only and unable to write to the platform, use a service account and set it to Group Viewer. **Note:** The [Get group level audit logs endpoint](https://snyk.docs.apiary.io/#reference/audit-logs/group-level-audit-logs/get-group-level-audit-logs) requires Group Admin permissions.
 
-Service accounts at the org level have only org admin and org collaborator permissions. Thus to set a service account to view-only you must use a group level service account.
+Service accounts at the Organization level have only org admin and org collaborator permissions. Thus to set a service account to view-only you must use a group-level service account.
 
 For more information see [Service accounts](../../../enterprise-configuration/service-accounts/).

docs/snyk-api/snyk-rest-api-overview/snyk-api-rate-limits.md

@@ -1,5 +1,5 @@
 # Snyk API rate limits
 
-For [Snyk API v1](https://snyk.docs.apiary.io/), each API has its own rate limit. The default is 2000 but some specific endpoints have lower limits. Refer to the reference docs for each endpoint to see the rate limits.
+For [Snyk V1 API](https://snyk.docs.apiary.io/), each API has its own rate limit. The default is 2000 but some specific endpoints have lower limits. Refer to the reference docs for each endpoint to see the rate limits.
 
 For [Snyk REST API](https://apidocs.snyk.io/), see Rate limiting in the reference docs overview.

docs/snyk-api/v1-api-overview/README.md

@@ -6,7 +6,7 @@ The Snyk API is available only for Enterprise plans. 
 For more information, see [Plans and pricing](https://snyk.io/plans).
 {% endhint %}
 
-The reference docs for the V1 API are provided in this section of the Snyk user docs.
+The reference docs for the V1 API are provided in the [Reference](../reference/) in the Snyk user docs.
 
 For information about how the V1 API works with the REST API and when to use the Snyk API, see the following sections on the [Snyk API ](../)main page:
 

docs/snyk-api/v1-api-overview/v1-api-errors.md

@@ -10,7 +10,7 @@ The V1 API uses standard HTTP error codes for error responses. 
 }
 ```
 
-The error reference will also be supplied in the `x-error-reference` header in the server reply.
+The error reference is also supplied in the `x-error-reference` header in the server reply.
 
 Example `500` response: