[Yandex Cloud documentation](../../../index.md) > [Yandex Identity and Access Management](../../index.md) > [Step-by-step guides](../index.md) > Authentication > Managing API keys

# Managing API keys

An [API key](../../concepts/authorization/api-key.md) is a secret key used for simplified [service account](../../concepts/users/service-accounts.md) authentication in the [Yandex Cloud API](../../../api-design-guide/index.md).

If you do not have a service account yet, [create one](../sa/create.md) and [assign roles to it](../sa/assign-role-for-sa.md).

## Viewing a list of API keys {#list-api-keys}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), click ![image](../../../_assets/console-icons/layout-side-content-left.svg) or ![image](../../../_assets/console-icons/chevron-down.svg) in the top panel and select the folder the service account belongs to.
  1. Navigate to **Identity and Access Management**.
  1. In the left-hand panel, select ![FaceRobot](../../../_assets/console-icons/face-robot.svg) **Service accounts** and then select the required service account.
  1. Under **API keys**, you will see a list of all available API keys.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  Get a list of API keys for a specific service account by entering the service account name:
  
  ```bash
  yc iam api-key list \
    --service-account-name <service_account_name>
  ```
  
  Result:
  
  ```text
  +----------------------+---------------------+--------------+--------------------------------+--------------------------------+------------+------------+
  |          ID          |     CREATED AT      | LAST USED AT |             SCOPE              |             SCOPES             | EXPIRES AT | MASKED KEY |
  +----------------------+---------------------+--------------+--------------------------------+--------------------------------+------------+------------+
  | aje5qvnhl67v******** | 2025-09-16 16:56:01 |              | yc.ai.foundationModels.execute | yc.ai.foundationModels.execute |            | ****rCG02w |
  | aje8be90datc******** | 2025-08-21 19:33:45 |              | yc.ai.foundationModels.execute | yc.ai.foundationModels.execute |            | ****u9hGKi |
  | aje1lmv2ipu3******** | 2025-09-16 16:56:25 |              | yc.ai.imageGeneration.execute  | yc.ai.imageGeneration.execute  |            | ****S5ejQ8 |
  +----------------------+---------------------+--------------+--------------------------------+--------------------------------+------------+------------+
  ```
  
  The `MASKED KEY` field shows the last six characters of the key’s secret part to help you [identify the key](../../concepts/authorization/api-key.md#identify-key).
  
  The folder specified in the CLI profile is used by default to search for the service account. You can specify a different folder using the `--folder-name` or `--folder-id` parameter.

- API {#api}

  Use the [List](../../api-ref/ApiKey/list.md) REST API method for the [ApiKey](../../api-ref/ApiKey/index.md) resource or the [ApiKeyService/List](../../api-ref/grpc/ApiKey/list.md) gRPC API call.

{% endlist %}

## Creating an API key {#create-api-key}

{% note info %}

Creating API keys for service accounts may be prohibited by [access policies](../../concepts/access-control/access-policies.md) at the [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder), [cloud](../../../resource-manager/concepts/resources-hierarchy.md#cloud), or [organization](../../../organization/concepts/organization.md) level.

{% endnote %}

To create a service account API key:

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), click ![image](../../../_assets/console-icons/layout-side-content-left.svg) or ![image](../../../_assets/console-icons/chevron-down.svg) in the top panel and select the folder the service account belongs to.
  1. Navigate to **Identity and Access Management**.
  1. In the left-hand panel, select ![FaceRobot](../../../_assets/console-icons/face-robot.svg) **Service accounts**.
  1. Select the service account to create an API key for. [Create](../sa/create.md) a new service account if you need to.
  1. In the top panel, click ![image](../../../_assets/console-icons/plus.svg) **Create new key** and select **Create API key**.
  1. Enter a description of the key so that you can easily find it in the management console.
  1. In the **Scope** field, select one or multiple [scopes](../../concepts/authorization/api-key.md#scoped-api-keys).
  1. Optionally, specify **Expires at**.
  1. Click **Create**.
  1. Save the ID and the secret key.
  
    {% note alert %}
  
    After you close this dialog, the key value will no longer be available.
  
    {% endnote %}

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the command for creating an API key:

      ```bash
      yc iam api-key create --help
      ```

  1. Get a list of service accounts in the default folder:

      ```bash
      yc iam service-account list
      ```

      Result:

      ```text
      +----------------------+------------------+-------------------------------+
      |          ID          |       NAME       |          DESCRIPTION          |
      +----------------------+------------------+-------------------------------+
      | aje6o61dvog2******** | my-robot         |                               |
      | aje9sda1ufvq******** | account_name     | account_description           |
      +----------------------+------------------+-------------------------------+
      ```

  1. Create an API key for the required service account and save the response to the `api_key.yaml` file:

      ```bash
      yc iam api-key create \
        --service-account-name <service_account_name> \
        --scopes <scope_1>[,<scope_2>,...,<scope_n>] \
        --expires-at <date_and_time> \
        > api_key.yaml
      ```

      Where:
      
      * `--service-account-name`: Service account name. This is a required setting.
      * `--scopes`: Key [scopes](../../concepts/authorization/api-key.md#scoped-api-keys). You can select one or multiple scopes. This is an optional setting.

          If the scope is not specified, the API key will be assigned the following scopes by default:

          * `yc.ai.imageGeneration.execute`
          * `yc.ai.languageModels.execute`
          * `yc.ai.speechkitStt.execute`
          * `yc.ai.speechkitTts.execute`
          * `yc.ai.translate.execute`
          * `yc.ai.vision.execute`
          * `yc.monitoring.manage`
          * `yc.search-api.execute`
          * `yc.serverless.containers.invoke`
          * `yc.serverless.functions.invoke`

      * `--expires-at`: Key expiration date and time in `YYYY-MM-DDThh:mm:ssZ` format, e.g., `2026-01-01T21:00:00Z`. This is an optional setting.
      * `api_key.yaml`: File to save the response to.
      
      As a result, you will get the `api_key.yaml` file with the API key value in the `secret` field:

      ```yaml
      api_key:
        id: ajeuo7ng2p6u********
        service_account_id: ajegtlf2q28a********
        created_at: "2025-04-04T10:23:08.722440521Z"
        scopes:
          - yc.monitoring.read
          - yc.serverless.functions.invoke
          - yc.postbox.send
        expires_at: "2026-01-01T21:00:00Z"
      secret: AQVN3sHvAWTemWB8QxHkunfG2x4q7G3O********
      ```

      Save the key value you got in a secure location. You will not be able to get it again.

- Terraform {#tf}

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../../terraform/authentication.md) using the appropriate method.

  1. In the Terraform configuration file, describe the resources you want to create:

      ```hcl
      resource "yandex_iam_service_account_api_key" "sa-api-key" {
        service_account_id = "<service_account_ID>"
        description        = "<key_description>"
        scopes              = ["<scope_1>", "<scope_2>", ..., "<scope_n>"]
        expires_at         = "<date_and_time>"
        pgp_key            = "<PGP_key>"
        output_to_lockbox  {
          secret_id            = "<Lockbox_secret_ID>"
          entry_for_secret_key = "<secret_key>"
        }
      }
      ```

      Where:

      * `service_account_id`: Service account [ID](../sa/get-id.md). This is a required setting.
      * `description`: Key description. This is an optional setting.
      * `scopes`: Key [scopes](../../concepts/authorization/api-key.md#scoped-api-keys). You can select one or multiple scopes. This is an optional setting.

          If the scope is not specified, the API key will be assigned the following scopes by default:

          * `yc.ai.imageGeneration.execute`
          * `yc.ai.languageModels.execute`
          * `yc.ai.speechkitStt.execute`
          * `yc.ai.speechkitTts.execute`
          * `yc.ai.translate.execute`
          * `yc.ai.vision.execute`
          * `yc.monitoring.manage`
          * `yc.search-api.execute`
          * `yc.serverless.containers.invoke`
          * `yc.serverless.functions.invoke`

      * `expires_at`: Key expiration date and time in `YYYY-MM-DDThh:mm:ssZ` format, e.g., `2026-01-01T21:00:00Z`. This is an optional setting.
      * `pgp_key`: Additional PGP key for encrypting a private key. Specify the public part of the key in Base64 encoding or in `keybase:keybaseusername` format. This is an optional setting.
      * `output_to_lockbox`: Description of the Yandex Lockbox [secret](../../../lockbox/concepts/secret.md) to save the API key value to, in order to avoid its possible leak through the `terraform.tfstate` file. This is an optional setting. Nested parameters:
          * `secret_id`: ID of the Yandex Lockbox secret to save the API key value to. The secret must be [custom](../../../lockbox/concepts/secret.md#secret-type).
          * `entry_for_secret_key`: Secret key to assign to the API key value being saved.

      For more information about the resources you can create with Terraform, see [this provider guide](../../../terraform/resources/iam_service_account_api_key.md).

  1. Create the resources:

      1. In the terminal, navigate to the configuration file directory.
      1. Make sure the configuration is correct using this command:
      
         ```bash
         terraform validate
         ```
      
         If the configuration is valid, you will get this message:
      
         ```bash
         Success! The configuration is valid.
         ```
      
      1. Run this command:
      
         ```bash
         terraform plan
         ```
      
         You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
      1. Apply the configuration changes:
      
         ```bash
         terraform apply
         ```
      
      1. Type `yes` and press **Enter** to confirm the changes.

      Terraform will create all the required resources. You can check the new resources and their settings using the [management console](https://console.yandex.cloud) or this [CLI](../../../cli/index.md) command:

      ```bash
      yc iam api-key list --service-account-id <service_account_ID>
      ```

- API {#api}

  Use the [create](../../api-ref/ApiKey/create.md) REST API method for the [ApiKey](../../api-ref/ApiKey/index.md) resource:

  ```bash
  export SERVICEACCOUNT_ID=<service_account_ID>
  export IAM_TOKEN=<token>
  curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --data "{
        \"serviceAccountId\": \"$SERVICEACCOUNT_ID\",
        \"scopes\": [\"<scope_1>\",\"<scope_2>\",...,\"<scope_n>\"],
        \"expiresAt\": \"<date_and_time>\"
    }" \
    https://iam.api.cloud.yandex.net/iam/v1/apiKeys
  ```

  Where:

  * `SERVICEACCOUNT_ID`: Service account [ID](../sa/get-id.md). This is a required setting.
  * `IAM_TOKEN`: [IAM token](../../concepts/authorization/iam-token.md). This is a required setting.
  * `scopes`: Key [scopes](../../concepts/authorization/api-key.md#scoped-api-keys). You can select one or multiple scopes. This is an optional setting.

      If the scope is not specified, the API key will be assigned the following scopes by default:

      * `yc.ai.imageGeneration.execute`
      * `yc.ai.languageModels.execute`
      * `yc.ai.speechkitStt.execute`
      * `yc.ai.speechkitTts.execute`
      * `yc.ai.translate.execute`
      * `yc.ai.vision.execute`
      * `yc.monitoring.manage`
      * `yc.search-api.execute`
      * `yc.serverless.containers.invoke`
      * `yc.serverless.functions.invoke`

  * `expiresAt`: Expiration date and time for the key with restricted access. This is an optional setting.

  Alternatively, you can create an API key via the [ApiKeyService/Create](../../api-ref/grpc/ApiKey/create.md) gRPC API call.

{% endlist %}

To learn how to transmit a key in a request, read the [guides for the respective services](../../concepts/authorization/api-key.md#supported-services) supporting this authentication method.

## Viewing available scopes for an API key {#available-scopes}

{% list tabs group=instructions %}

- Management console

  1. In the [management console](https://console.yandex.cloud), click ![image](../../../_assets/console-icons/layout-side-content-left.svg) or ![image](../../../_assets/console-icons/chevron-down.svg) in the top panel and select the folder the service account belongs to.
   1. In the list of services, select **Identity and Access Management**.
   1. In the left-hand panel, select ![FaceRobot](../../../_assets/console-icons/face-robot.svg) **Service accounts**.
   1. In the list that opens, select the service account you want to view scopes for.
   1. In the ![flag](../../../_assets/console-icons/flag.svg) **Overview** tab, locate the API key under **API keys**.
   1. In its info row, you will find all available scopes of the API key in the **Scope** column.

- CLI {#cli}

  To view available [scopes](../../concepts/authorization/api-key.md#scoped-api-keys) of an API key, run this command:

  ```bash
  yc iam api-key list-scopes
  ```

- API {#api}

  To view the available [scopes](../../concepts/authorization/api-key.md#scoped-api-keys) of an API key, use the [ListScopes](../../api-ref/ApiKey/listScopes.md) REST API method for the [ApiKey](../../api-ref/ApiKey/index.md) resource or the [ApiKeyService/ListScopes](../../api-ref/grpc/ApiKey/listScopes.md) gRPC API call.

{% endlist %}

## Adding a description when creating an API key {#add-description}

To add an API key description when creating the key:

{% list tabs group=instructions %}

- CLI {#cli}

  ```bash
  yc iam api-key create \
    --service-account-name <service_account_name> \
    --description "this API-key is for my-robot" \
    --scopes yc.monitoring.read,yc.postbox.send,yc.serverless.functions.invoke
  ```

  Where:

  * `--service-account-name`: Service account [name](../sa/get-id.md). This is a required setting.
  * `--description`: API key description. This is an optional setting.
  * `--scopes`: Key [scopes](../../concepts/authorization/api-key.md#scoped-api-keys). This is an optional setting.

- Terraform {#tf}

  ```hcl
  resource "yandex_iam_service_account_api_key" "sa-api-key" {
    service_account_id = "<service_account_ID>"
    description        = "this API-key is for my-robot"
    scopes             = ["yc.monitoring.read", "yc.postbox.send", "yc.serverless.functions.invoke"]
  }
  ```

  Where:

  * `service_account_id`: Service account [ID](../sa/get-id.md). This is a required setting.
  * `description`: Key description. This is an optional setting.
  * `scopes`: Key [scopes](../../concepts/authorization/api-key.md#scoped-api-keys). This is an optional setting.

- API {#api}

  Send your request:

  ```bash
  export SERVICEACCOUNT_ID=<service_account_ID>
  export IAM_TOKEN=<IAM_token>
  curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --data "{
        \"serviceAccountId\": \"$SERVICEACCOUNT_ID\",
        \"description\": \"this API-key is for my-robot\",
        \"scopes\": [\"yc.monitoring.read\",\"yc.postbox.send\",\"yc.serverless.functions.invoke\"]
    }" \
    https://iam.api.cloud.yandex.net/iam/v1/apiKeys
  ```

  Where:

  * `SERVICEACCOUNT_ID`: [Service account ID](../sa/get-id.md). This is a required setting.
  * `IAM_TOKEN`: [IAM token](../../concepts/authorization/iam-token.md). This is a required setting.
  * `scopes`: Key [scopes](../../concepts/authorization/api-key.md#scoped-api-keys). This is an optional setting.

{% endlist %}

## Deleting an API key {#delete-api-key}

To delete a service account API key:

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), click ![image](../../../_assets/console-icons/layout-side-content-left.svg) or ![image](../../../_assets/console-icons/chevron-down.svg) in the top panel and select the folder the service account belongs to.
  1. In the list of services, select **Identity and Access Management**.
  1. In the left-hand panel, select ![FaceRobot](../../../_assets/console-icons/face-robot.svg) **Service accounts** and then select the required service account.
  1. Under **API keys**, click ![image](../../../_assets/console-icons/ellipsis.svg) in the row with the API key to delete, and select **Delete**.
  1. In the window that opens, confirm the deletion.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. Get a list of API keys for a specific service account by entering the service account name:
     
     ```bash
     yc iam api-key list \
       --service-account-name <service_account_name>
     ```
     
     Result:
     
     ```text
     +----------------------+---------------------+--------------+--------------------------------+--------------------------------+------------+------------+
     |          ID          |     CREATED AT      | LAST USED AT |             SCOPE              |             SCOPES             | EXPIRES AT | MASKED KEY |
     +----------------------+---------------------+--------------+--------------------------------+--------------------------------+------------+------------+
     | aje5qvnhl67v******** | 2025-09-16 16:56:01 |              | yc.ai.foundationModels.execute | yc.ai.foundationModels.execute |            | ****rCG02w |
     | aje8be90datc******** | 2025-08-21 19:33:45 |              | yc.ai.foundationModels.execute | yc.ai.foundationModels.execute |            | ****u9hGKi |
     | aje1lmv2ipu3******** | 2025-09-16 16:56:25 |              | yc.ai.imageGeneration.execute  | yc.ai.imageGeneration.execute  |            | ****S5ejQ8 |
     +----------------------+---------------------+--------------+--------------------------------+--------------------------------+------------+------------+
     ```
     
     The `MASKED KEY` field shows the last six characters of the key’s secret part to help you [identify the key](../../concepts/authorization/api-key.md#identify-key).
     
     The folder specified in the CLI profile is used by default to search for the service account. You can specify a different folder using the `--folder-name` or `--folder-id` parameter.
  1. Delete the API key by specifying its ID:

      ```bash
      yc iam api-key delete <API_key_ID>
      ```

- Terraform {#tf}

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../../terraform/authentication.md) using the appropriate method.

  1. Open the Terraform configuration file and delete the section with the API key description.

      Example API key description in the Terraform configuration:

      ```hcl
      resource "yandex_iam_service_account_api_key" "sa-api-key" {
        service_account_id = "<service_account_ID>"
        description        = "<key_description>"
        pgp_key            = "<PGP_key>"
      }
      ```

      For more information about the resources you can create with Terraform, see [this provider guide](../../../terraform/resources/iam_service_account_api_key.md).

  1. Make sure the configuration files are correct.

      1. In the terminal, navigate to the directory where you created your configuration file.
      1. Run a check using this command:

          ```bash
          terraform plan
          ```

      If the configuration is correct, the terminal will display a list of the resources and their settings. Otherwise, Terraform will show any detected errors.

  1. Deploy the cloud resources.

      1. If the configuration is correct, run this command:

          ```bash
          terraform apply
          ```

      1. Confirm creating and deleting the resources by typing `yes` in the terminal and clicking **Enter**.

      This will create or delete all the resources you need in the specified folder. You can check the new resources and their settings or make sure the resources were deleted using the [management console](https://console.yandex.cloud) and this CLI command:

      ```bash
      yc iam api-key list --service-account-id <service_account_ID>
      ```

- API {#api}

  Use the [delete](../../api-ref/ApiKey/delete.md) REST API method for the [ApiKey](../../api-ref/ApiKey/index.md) resource:

  ```bash
  export APIKEY_ID=<API_key_ID>
  export IAM_TOKEN=<IAM_token>
  curl \
      --request DELETE \
      --header "Authorization: Bearer $IAM_TOKEN" \
      https://iam.api.cloud.yandex.net/iam/v1/apiKeys/$APIKEY_ID
  ```

  You can also delete the API key using the [ApiKeyService/Delete](../../api-ref/grpc/ApiKey/delete.md) gRPC API call.

{% endlist %}

#### Useful links {#see-also}

* [API key](../../concepts/authorization/api-key.md)
* [Yandex Cloud services that support API keys](../../concepts/authorization/api-key.md#supported-services)