Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Setting up access to Yandex Foundation Models with API keys

Written by
Improved by
Updated at April 22, 2025

Yandex Foundation Models is part of Yandex Cloud and uses its authentication and authorization mechanism. You can send requests to Foundation Models models under your user account by authenticating with an IAM token. This is the most secure way to do a quick trial as the IAM token lifetime is limited to 12 hours. However, we recommend accessing the API as a service account with an API key.

To set up authorization with an API key as a service account:

  1. Get your cloud ready.
  2. Create a service account.
  3. Assign roles to the service account.
  4. Create an API key.

Get your cloud ready

Sign up for Yandex Cloud and create a billing account:

  1. Go to the management console and log in to Yandex Cloud or create an account if you do not have one yet.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one.

If you have an active billing account, you can go to the cloud page to create or select a folder for your infrastructure to operate in.

Learn more about clouds and folders.

Create a service account

  1. Go to the management console.

  2. On the left side of the screen, click the line with the name of the folder where you want to create a service account.

  3. In the list of services, select Identity and Access Management.

  4. Click Create service account.

  5. Enter a name for the service account.

    The name format requirements are as follows:

    • It must be from 2 to 63 characters long.
    • It may contain lowercase Latin letters, numbers, and hyphens.
    • It must start with a letter and cannot end with a hyphen.

    Make sure the service account name is unique within your cloud.

  6. Click Create.

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

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id settings.

Create a service account:

yc iam service-account create --name sa-api

Where --name is the service account name in the following format:

  • It must be from 2 to 63 characters long.
  • It may contain lowercase Latin letters, numbers, and hyphens.
  • It must start with a letter and cannot end with a hyphen.

Result:

id: ajehr0to1g8b********
folder_id: b1gv87ssvu49********
created_at: "2023-03-04T09:03:11.665153755Z"
name: sa-api

Create a service account using the create REST API method for the ServiceAccount resource:

curl \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer <IAM_token>" \
  --data '{
    "folderId": "<folder_ID>",
    "name": "<service_account_name>",
    "description": "service account for api"
  }' \
  https://iam.api.cloud.yandex.net/iam/v1/serviceAccounts

Where:

  • <IAM_token>: Valid authorization token.

  • <folder_ID>: ID of the folder hosting the services.

  • <service_account_name>: Service account name, e.g., sa-api. The naming requirements are as follows:

    • It must be from 2 to 63 characters long.
    • It may contain lowercase Latin letters, numbers, and hyphens.
    • It must start with a letter and cannot end with a hyphen.

You can also create a service account using the ServiceAccountService/Create gRPC call.

Assign roles to the service account

  1. In the management console, select the cloud or folder.

  2. Navigate to the Access bindings tab.

  3. Click Configure access.

  4. Select the service account you created earlier.

  5. Click Add role and select the required roles:

    • To use text generation models, add the ai.languageModels.user role.
    • To use image generation models, add the ai.imageGeneration.user role.
    • To create datasets and tune models, add the ai.datasets.editor and ai.models.editor roles.
    • To create an assistant, add the ai.assistants.editor role.

    You can assign multiple roles at the same time. Learn more about Foundation Models roles.

  6. Click Save.

Run this command:

yc resource-manager folder add-access-binding <folder_ID> \
   --role <role_ID> \
   --subject serviceAccount:<service_account_ID>

Where --role is the role for using Foundation Models:
* ai.languageModels.user: To use text generation models.
* ai.imageGeneration.user: To use image generation models.
* ai.datasets.editor and ai.models.editor: To create datasets and tune models.
* ai.assistants.editor: To create an assistant.

Learn more about Foundation Models roles.

Assign the required role to the service account using the setAccessBindings REST API method for the ServiceAccount resource:

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <IAM_token>" \
  --data '{
    "accessBindingDeltas": [{
      "action": "ADD",
      "accessBinding": {
        "roleId": "<role_ID>",
        "subject": {
          "id": "<service_account_ID>",
          "type": "serviceAccount"
          }
        }
      }
    ]
   }' \
  https://resource-manager.api.cloud.yandex.net/resource-manager/v1/folders/<folder_ID>:updateAccessBindings

Where:

  • <IAM_token>: Valid authorization token.

  • <role_ID>: Role for working with Foundation Models:

    • ai.languageModels.user: To use text generation models.
    • ai.imageGeneration.user: To use image generation models.
    • ai.datasets.editor and ai.models.editor: To create datasets and tune models.
    • ai.assistants.editor: To create an assistant.

    Learn more about Foundation Models roles.

  • <service_account_ID>: ID of the service account you created earlier.

You can also assign service account roles using the ServiceAccountService/SetAccessBindings gRPC call.

Create an API key

  1. In the management console, navigate to the folder the service account belongs to.

  2. From the list of services, select 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. Select Scope to specify how you are going to use the API key:

    • yc.ai.languageModels.execute: Enables using the API key to work with text generation models.
    • yc.ai.imageGeneration.execute: Enables using the API key to work with image generation models.
    • yc.ai.foundationModels.execute: Enables using the API key to work with all Foundation Models models.

  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 not be shown again.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id settings.

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

    yc iam api-key create --help

  2. Select a service account, e.g., sa-api:

    yc iam service-account list

    Result:

    +----------------------+------------------+-------------------------------+
|          ID          |       NAME       |          DESCRIPTION          |
+----------------------+------------------+-------------------------------+
| aje6o61dvog2******** | sa-api           |                               |
+----------------------+------------------+-------------------------------+

  3. Create an API key for the selected service account and save the response to a file:

    yc iam api-key create --service-account-name sa-api > api-key.yaml

    The secret property in the response will contain the API key:

    api_key:
  id: ajeke74kbp5b********
  service_account_id: ajepg0mjt06********
  created_at: "2019-04-09T08:41:27Z"
secret: AQVN1HHJReSrfo9jU3aopsXrJyfq_UHs********

Create an API key using the create REST API method for the ApiKey resource:

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <IAM_token>" \
  --data "{ \"serviceAccountId\": \"<service_account_ID>\" }" \
  https://iam.api.cloud.yandex.net/iam/v1/apiKeys

Where:

  • <IAM_token>: Valid authorization token.
  • <service_account_ID>: sa-api service account ID.

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

Now you can send requests to Foundation Models models as a service account.

Previous
Disabling request logging
Next
Estimating request size in tokens