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

Setting up access with API keys

Written by
Improved by
Updated at May 13, 2025

To ensure security and facilitate your work with Yandex Vision OCR and Yandex Translate, we recommend using authorization on behalf of a service account with an API key.

To set up authorization on behalf of a service account:

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

Prepare your cloud

Sign up in Yandex Cloud and create a billing account:

  1. Navigate to the management console and log in to Yandex Cloud or register a new account.
  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 and link a cloud to it.

If you have an active billing account, you can navigate 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. In the management console, select the folder where you want to create a service account.

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

  3. Click Create service account.

  4. Enter a name for the service account, e.g., sa-api.

    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.

  5. Click Create.

If you do not have the Yandex Cloud (CLI) command line interface 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.

Run the following command to 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 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.

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

Assign roles to the service account

  1. On the management console home page, select a folder.
  2. Click the Access permissions tab.
  3. Find the sa-api account in the list and click .
  4. Click Edit roles.
  5. Click Add role in the dialog box that opens and select the ai.translate.user role for Yandex Translate or ai.vision.user for Yandex Vision OCR.
  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 ai.translate.user for Yandex Translate or ai.vision.user for Yandex Vision OCR.

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>: ai.translate.user for Yandex Translate or ai.vision.user for Yandex Vision OCR.
  • <service_account_ID>: sa-api service account ID.

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

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. 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 sa-api service account and save the response to the 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********

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

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 Yandex Vision OCR and Yandex Translate services on behalf of your service account.

Enter your API key when accessing Yandex Cloud resources via the API. Provide the API key in the Authorization header in the following format:

Authorization: Api-Key <API_key>
Previous
Base64 encoding
Next
All tutorials