Managing API keys

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

1. See the description of the create API key command:

   yc iam api-key create --help
   

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

   yc iam service-account list
   

   Result:

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

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

   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 parameter.

   • --scopes: Key scopes. You can select one or multiple scopes. This is an optional parameter.

     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 parameter.

   • 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:

   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.

If you do not have Terraform yet, install it and configure its Yandex Cloud provider.

1. In the Terraform configuration file, define the parameters of the resources you want to create:

   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. This is a required parameter.

   • description: Key description. This is an optional parameter.

   • scopes: Key scopes. You can select one or multiple scopes. This is an optional parameter.

     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 parameter.

   • 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 parameter.

   • output_to_lockbox: Description of the Yandex Lockbox secret to save the API key value to, in order to avoid its possible leak through the terraform.tfstate file. This is an optional parameter. Nested parameters:

     • secret_id: ID of the Yandex Lockbox secret to save the API key value to. The secret must be custom.
     • entry_for_secret_key: Secret key to assign to the API key value being saved.

   To learn more about the resources you can create with Terraform, see the Terraform documentation.

2. Create the resources:

   1. In the terminal, change to the folder where you edited the configuration file.

   2. Make sure the configuration file is correct using the command:

      terraform validate
      

      If the configuration is correct, the following message is returned:

      Success! The configuration is valid.
      

   3. Run the command:

      terraform plan
      

      The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.

   4. Apply the configuration changes:

      terraform apply
      

   5. Confirm the changes: type yes in the terminal and press Enter.

   Terraform will create all the required resources. You can check your new resources and their settings in the management console or using this CLI command:

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

Use the create REST API method for the ApiKey resource:

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. This is a required parameter.

• IAM_TOKEN: IAM token. This is a required parameter.

• scopes: Key scopes. You can select one or multiple scopes. This is an optional parameter.

  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 parameter.

You can also create an API key using the ApiKeyService/Create gRPC API call.

To view the available scopes of an API key, use the ListScopes REST API method for the ApiKey resource or the ApiKeyService/ListScopes gRPC API call.

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. This is a required parameter.
• description: Key description. This is an optional parameter.
• scopes: Key scopes. This is an optional parameter.

Send your request:

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. This is a required parameter.
• IAM_TOKEN: IAM token. This is a required parameter.
• scopes: Key scopes. This is an optional parameter.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

1. Get a list of API keys for a specific service account by entering the service account name:

   yc iam api-key list \
     --service-account-name <service_account_name>
   

   Result:

   +----------------------+---------------------+
   |          ID          |     CREATED AT      |
   +----------------------+---------------------+
   | ajenhvftf77r******** | 2022-03-13 21:15:40 |
   | ajeq610sgh05******** | 2022-03-13 21:14:43 |
   +----------------------+---------------------+
   

   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.

2. Delete the API key by specifying its ID:

   yc iam api-key delete <API_key_ID>
   

If you do not have Terraform yet, install it and configure its Yandex Cloud provider.

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

   Example API key description in the Terraform configuration:

   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 the relevant provider documentation.

2. Make sure the configuration files are correct.

   1. In the command line, go to the directory where you created the configuration file.

   2. Run a check using this command:

      terraform plan
      

   If the configuration is correct, the terminal will display a list of new resources with their properties. If the configuration contains any errors, Terraform will point them out.

3. Deploy the cloud resources.

   1. If the configuration does not contain any errors, run this command:

      terraform apply
      

   2. Confirm creating and deleting the resources by typing yes in the terminal and clicking Enter.

   This will create or delete all 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 and this CLI command:

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

Use the delete REST API method for the ApiKey resource:

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 gRPC API call.