Управление API-ключами

Статья создана

Yandex Cloud

Улучшена

mmerihsesh

Обновлена 28 апреля 2025 г.

Создать API-ключ
- Посмотреть доступные области действия API-ключа
- Примеры
Удалить API-ключ

API-ключ — секретный ключ, используемый для упрощенной аутентификации сервисного аккаунта в API Yandex Cloud.

Если у вас еще нет сервисного аккаунта, создайте его и назначьте ему роли.

Создать API-ключ

Чтобы создать API-ключ сервисного аккаунта:

Консоль управления

CLI

Terraform

API

В консоли управления перейдите в каталог, которому принадлежит сервисный аккаунт.
В списке сервисов выберите Identity and Access Management.
На панели слева выберите Сервисные аккаунты.
Выберите сервисный аккаунт, для которого вы хотите создать API-ключ. При необходимости создайте новый сервисный аккаунт.
На панели сверху нажмите кнопку Создать новый ключ и выберите пункт Создать API-ключ.
Задайте описание ключа, чтобы потом было проще найти его в консоли управления.
В поле Область действия выберите одну или несколько областей действия.
(Опционально) Укажите Срок действия.
Нажмите кнопку Создать.
Сохраните идентификатор и секретный ключ.

Внимание

После закрытия диалога значение ключа будет недоступно.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Посмотрите описание команды создания API-ключа:
```
yc iam api-key create --help
```

Получите список сервисных аккаунтов в каталоге по умолчанию:

yc iam service-account list

Результат:

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

Создайте API-ключ для нужного сервисного аккаунта и запишите ответ в файл api_key.yaml:
```
yc iam api-key create \
  --service-account-name <имя_сервисного_аккаунта> \
  --scopes <область_действия_1>[,<область_действия_2>,...,<область_действия_n>] \
  --expires-at <дата_и_время> \
  > api_key.yaml
```
Где:
- --service-account-name — имя сервисного аккаунта. Обязательный параметр.
- --scopes — области действия ключа. Можно указать одну или несколько областей действия. Необязательный параметр.
  
  Если параметр не задан, API-ключу будут по умолчанию назначены следующие области действия:
  - 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 — дата и время истечения срока действия ключа в формате YYYY-MM-DDThh:mm:ssZ. Например: 2026-01-01T21:00:00Z. Необязательный параметр.
- api_key.yaml — файл, в который сохраняется ответ.
В результате вы получите файл api_key.yaml, который содержит значение API-ключа в поле secret:
```
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********
```
Надежно сохраните полученное значение ключа: повторно получить его будет невозможно.

Если у вас еще нет Terraform, установите его и настройте провайдер Yandex Cloud.

Опишите в конфигурационном файле Terraform параметры ресурсов, которые необходимо создать:
```
resource "yandex_iam_service_account_api_key" "sa-api-key" {
  service_account_id = "<идентификатор_сервисного_аккаунта>"
  description        = "<описание_ключа>"
  scopes              = ["<область_действия_1>", "<область_действия_2>", ..., "<область_действия_n>"]
  expires_at         = "<дата_и_время>"
  pgp_key            = "<pgp-ключ>"
  output_to_lockbox  {
    secret_id             = "<идентификатор_секрета_Lockbox>"
    entry_for_secret_key = "<ключ_секрета>"
  }
}
```
Где:
- service_account_id — идентификатор сервисного аккаунта. Обязательный параметр.
- description — описание ключа. Необязательный параметр.
- scopes — области действия ключа. Можно указать одну или несколько областей действия. Необязательный параметр.
  
  Если параметр не задан, API-ключу будут по умолчанию назначены следующие области действия:
  - 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 — дата и время истечения срока действия ключа в формате YYYY-MM-DDThh:mm:ssZ. Например: 2026-01-01T21:00:00Z. Необязательный параметр.
- pgp_key — дополнительный PGP-ключ для шифрования закрытого ключа. Указывается публичная часть ключа в кодировке base64, либо в виде keybase:keybaseusername. Необязательный параметр.
- output_to_lockbox — описание секрета Yandex Lockbox, в который будет сохранено значение API-ключа, во избежание его возможной утечки через файл состояния terraform.tfstate. Необязательный параметр. Вложенные параметры:
  - secret_id — идентификатор секрета Yandex Lockbox, в который будет сохранено значение API-ключа. Секрет должен быть пользовательского типа.
  - entry_for_secret_key — ключ секрета, который будет присвоен сохраняемому значению API-ключа.
Более подробную информацию о ресурсах, которые вы можете создать с помощью Terraform, см. в документации провайдера.
Создайте ресурсы:
1. В терминале перейдите в папку, где вы отредактировали конфигурационный файл.
2. Проверьте корректность конфигурационного файла с помощью команды:
```
terraform validate
```
  Если конфигурация является корректной, появится сообщение:
```
Success! The configuration is valid.
```
3. Выполните команду:
```
terraform plan
```
  В терминале будет выведен список ресурсов с параметрами. На этом этапе изменения не будут внесены. Если в конфигурации есть ошибки, Terraform на них укажет.
4. Примените изменения конфигурации:
```
terraform apply
```
5. Подтвердите изменения: введите в терминале слово yes и нажмите Enter.
Terraform создаст все требуемые ресурсы. Проверить появление ресурсов и их настройки можно в консоли управления или с помощью команды CLI:
```
yc iam api-key list --service-account-id <идентификатор_сервисного_аккаунта>
```

Воспользуйтесь методом REST API create для ресурса ApiKey:

export SERVICEACCOUNT_ID=<идентификатор_сервисного_аккаунта>
export IAM_TOKEN=<токен>
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $IAM_TOKEN" \
  --data "{
      \"serviceAccountId\": \"$SERVICEACCOUNT_ID\",
      \"scopes\": [\"<область_действия_1>\",\"<область_действия_2>\",...,\"<область_действия_n>\"],
      \"expiresAt\": \"<дата_и_время>\"
  }" \
  https://iam.api.cloud.yandex.net/iam/v1/apiKeys

Где:

SERVICEACCOUNT_ID — идентификатор сервисного аккаунта. Обязательный параметр.
IAM_TOKEN — IAM-токен. Обязательный параметр.
scopes — области действия ключа. Можно указать одну или несколько областей действия. Необязательный параметр.

Если параметр не задан, API-ключу будут по умолчанию назначены следующие области действия:
- 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 — дата и время истечения срока действия ключа с ограниченным доступом. Необязательный параметр.

Также API-ключ можно создать с помощью вызова gRPC API ApiKeyService/Create.

О том, как передать ключ в запросе, читайте в документации сервисов, которые поддерживают такой способ аутентификации.

Посмотреть доступные области действия API-ключа

CLI

API

Чтобы посмотреть доступные области действия API-ключа, выполните команду:

yc iam api-key list-scopes

Результат:

- 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.monitoring.manage
- yc.monitoring.read
- yc.postbox.send
- yc.search-api.execute
- yc.serverless.containers.invoke
- yc.serverless.functions.invoke
- yc.ydb.tables.manage
- yc.ydb.topics.manage

Чтобы посмотреть доступные области действия API-ключа, воспользуйтесь методом REST API ListScopes для ресурса ApiKey или вызовом gRPC API ApiKeyService/ListScopes.

Примеры

Добавить описание при создании API-ключа

Чтобы добавить описание API-ключа при его создании:

CLI

Terraform

API

yc iam api-key create \
  --service-account-name <имя_сервисного_аккаунта> \
  --description "this API-key is for my-robot" \
  --scopes yc.monitoring.read,yc.postbox.send,yc.serverless.functions.invoke

Где:

--service-account-name — имя сервисного аккаунта. Обязательный параметр.
--description — описание API-ключа. Необязательный параметр.
--scopes — области действия ключа. Необязательный параметр.

resource "yandex_iam_service_account_api_key" "sa-api-key" {
  service_account_id = "<идентификатор_сервисного_аккаунта>"
  description        = "this API-key is for my-robot"
  scopes             = ["yc.monitoring.read", "yc.postbox.send", "yc.serverless.functions.invoke"]
}

Где:

service_account_id — идентификатор сервисного аккаунта. Обязательный параметр.
description — описание ключа. Необязательный параметр.
scopes — области действия ключа. Необязательный параметр.

Отправьте запрос:

export SERVICEACCOUNT_ID=<идентификатор_сервисного_аккаунта>
export IAM_TOKEN=<IAM-токен>
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

Где:

SERVICEACCOUNT_ID - идентификатор сервисного аккаунта. Обязательный параметр.
IAM_TOKEN - IAM-токен. Обязательный параметр.
scopes — области действия ключа. Необязательный параметр.

Удалить API-ключ

Чтобы удалить API-ключ сервисного аккаунта:

Консоль управления

CLI

Terraform

API

В консоли управления перейдите в каталог, которому принадлежит сервисный аккаунт.
В списке сервисов выберите Identity and Access Management.
На панели слева выберите Сервисные аккаунты и выберите нужный сервисный аккаунт.
В блоке API-ключи в строке с API-ключом, который нужно удалить, нажмите и выберите Удалить.
В открывшемся окне подтвердите удаление.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

Получите список API-ключей для определенного сервисного аккаунта, указав его имя:
```
yc iam api-key list \
  --service-account-name <имя_сервисного_аккаунта>
```
Результат:
```
+----------------------+---------------------+
|          ID          |     CREATED AT      |
+----------------------+---------------------+
| ajenhvftf77r******** | 2022-03-13 21:15:40 |
| ajeq610sgh05******** | 2022-03-13 21:14:43 |
+----------------------+---------------------+
```
По умолчанию для поиска сервисного аккаунта используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name или --folder-id.
Удалите API-ключ, указав его идентификатор:
```
yc iam api-key delete <идентификатор_API-ключа>
```

Если у вас еще нет Terraform, установите его и настройте провайдер Yandex Cloud.

Откройте файл конфигурации Terraform и удалите секцию с описанием API-ключа.

Пример описания API-ключа в конфигурации Terraform:
```
resource "yandex_iam_service_account_api_key" "sa-api-key" {
    service_account_id = "<идентификатор_сервисного_аккаунта>"
    description        = "<описание_ключа>"
    pgp_key            = "<pgp-ключ>"
}
```
Более подробную информацию о ресурсах, которые вы можете создать с помощью Terraform, см. в документации провайдера.
Проверьте корректность конфигурационных файлов.
1. В командной строке перейдите в папку, где вы создали конфигурационный файл.
2. Выполните проверку с помощью команды:
```
terraform plan
```
Если конфигурация описана верно, в терминале отобразится список создаваемых ресурсов и их параметров. Если в конфигурации есть ошибки, Terraform на них укажет.
Разверните облачные ресурсы.
1. Если в конфигурации нет ошибок, выполните команду:
```
terraform apply
```
2. Подтвердите создание или удаление ресурсов: введите в терминал слово yes и нажмите Enter.
После этого в указанном каталоге будут созданы или удалены все требуемые ресурсы. Проверить появление ресурсов и их настройки или удаление ресурсов можно в консоли управления, а также с помощью команды CLI:
```
yc iam api-key list --service-account-id <идентификатор_сервисного_аккаунта>
```

Воспользуйтесь методом REST API delete для ресурса ApiKey:

export APIKEY_ID=<идентификатор_API-ключа>
export IAM_TOKEN=<IAM-токен>
curl \
    --request DELETE \
    --header "Authorization: Bearer $IAM_TOKEN" \
    https://iam.api.cloud.yandex.net/iam/v1/apiKeys/$APIKEY_ID

Также API-ключ можно удалить вызовом gRPC API ApiKeyService/Delete.

Управление API-ключами

Создать API-ключ

Посмотреть доступные области действия API-ключа

Примеры

Добавить описание при создании API-ключа

Удалить API-ключ

См. также

Была ли статья полезна?

Управление API-ключами

Создать API-ключСоздать API-ключ

Посмотреть доступные области действия API-ключаПосмотреть доступные области действия API-ключа

ПримерыПримеры

Добавить описание при создании API-ключаДобавить описание при создании API-ключа

Удалить API-ключУдалить API-ключ

См. такжеСм. также

Была ли статья полезна?

Создать API-ключ

Посмотреть доступные области действия API-ключа

Примеры

Добавить описание при создании API-ключа

Удалить API-ключ

См. также