Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Managing API keys

Written by
Updated at May 15, 2026

An API key is a secret key used for simplified service account authentication in the Yandex Cloud API.

If you do not have a service account yet, create one and assign roles to it.

Viewing a list of API keys

  1. In the management console, click or in the top panel and select the folder the service account belongs to.
  2. Go to Identity and Access Management.
  3. In the left-hand panel, select Service accounts and then select the required service account.
  4. Under API keys, you will see a list of all available API keys.

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

The folder used by default is the one specified when creating 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:

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

Result:

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

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.

Use the List REST API method for the ApiKey resource or the ApiKeyService/List gRPC API call.

Creating an API key

Note

Creating API keys for service accounts may be prohibited by access policies at the folder, cloud, or organization level.

To create a service account API key:

  1. In the management console, click or in the top panel and select the folder the service account belongs to.
  2. Go to Identity and Access Management.
  3. In the left-hand panel, select Service accounts.
  4. Select the service account to create an API key for. Create a new service account if you need to.
  5. In the top panel, click Create new key and select Create API key.
  6. Enter a description of the key so that you can easily find it in the management console.
  7. In the Scope field, select one or multiple scopes.
  8. Optionally, specify Expires at.
  9. Click Create.
  10. Save the ID and secret key.

Alert

After you close this dialog, the key value will no longer be available.

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

The folder used by default is the one specified when creating 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:

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

    • --scopes: Key scopes. 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:

    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 the Yandex Cloud provider.

  1. In the Terraform configuration file, describe 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 setting.

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

    • scopes: Key scopes. 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 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.
      • 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.

  2. Create the required resources:

    1. In the terminal, navigate to the configuration file directory.

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

      terraform validate

      If the configuration is valid, you will get this message:

      Success! The configuration is valid.

    3. Run this command:

      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.

    4. Apply the configuration changes:

      terraform apply

    5. 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 either 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 setting.

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

  • scopes: Key scopes. 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 gRPC API call.

To learn how to transmit a key in a request, read the guides for the respective services supporting this authentication method.

Viewing available scopes for an API key

  1. In the management console, click or in the top panel and select the folder the service account belongs to.
  2. In the list of services, select Identity and Access Management.
  3. In the left-hand panel, select Service accounts.
  4. In the list that opens, select the service account you want to view scopes for.
  5. In the Overview tab, locate the API key under API keys.
  6. In its info row, you will find all available scopes of the API key in the Scope column.

To view available scopes of an API key, run this command:

yc iam api-key list-scopes

Result:

- yc.ai.foundationModels.execute
- 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.logging.write
- yc.monitoring.manage
- yc.monitoring.read
- yc.monium.logs.write
- yc.monium.metrics.write
- yc.monium.traces.write
- yc.monium.telemetry.write
- yc.postbox.send
- yc.search-api.execute
- yc.serverless.containers.invoke
- yc.serverless.functions.invoke
- yc.ydb.tables.manage
- yc.ydb.topics.manage

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.

Examples

Adding a description when creating an API key

To add an API key description when creating the key:

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

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

Deleting an API key

To delete a service account API key:

  1. In the management console, click or in the top panel and select the folder the service account belongs to.
  2. In the list of services, select Identity and Access Management.
  3. In the left-hand panel, select Service accounts and then select the required service account.
  4. Under API keys, click in the row with the API key to delete, and select Delete.
  5. In the window that opens, confirm the deletion.

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

The folder used by default is the one specified when creating 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:

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

    Result:

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

    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 the 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 this provider guide.

  2. Validate your configuration files.

    1. In the terminal, navigate to the directory where you created your configuration file.

    2. Run a check using the following command:

      terraform plan

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

  3. Deploy the cloud resources.

    1. If the configuration is correct, 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 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 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.

See also

Previous
Managing static access keys
Next
Managing authorized keys