From 1f71bdf4212ee3d7a52b1ed785be7b287b4547aa Mon Sep 17 00:00:00 2001 From: Ann Wiley Date: Thu, 9 Jan 2025 01:19:30 +0000 Subject: [PATCH] GITBOOK-8665: API: Create one how to authenticate page using Authentication for API --- .../rest-api/authentication-for-api/README.md | 50 ++++++++++++++----- .../authenticate-for-the-api.md | 32 +----------- docs/snyk-cli/authenticate-to-use-the-cli.md | 2 +- 3 files changed, 40 insertions(+), 44 deletions(-) diff --git a/docs/snyk-api/rest-api/authentication-for-api/README.md b/docs/snyk-api/rest-api/authentication-for-api/README.md index da7ab275e1fa..638404925a4b 100644 --- a/docs/snyk-api/rest-api/authentication-for-api/README.md +++ b/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" +} +``` diff --git a/docs/snyk-api/rest-api/authentication-for-api/authenticate-for-the-api.md b/docs/snyk-api/rest-api/authentication-for-api/authenticate-for-the-api.md index 8dab2481e840..f741714ac50f 100644 --- a/docs/snyk-api/rest-api/authentication-for-api/authenticate-for-the-api.md +++ b/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](./). diff --git a/docs/snyk-cli/authenticate-to-use-the-cli.md b/docs/snyk-cli/authenticate-to-use-the-cli.md index 209747cef0f4..e39339517b8f 100644 --- a/docs/snyk-cli/authenticate-to-use-the-cli.md +++ b/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).