Contact UsGet started

Setting up access with API keys

Written by
Updated at December 16, 2024

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

    • The name must be from 3 to 63 characters long.
    • It may contain lowercase Latin letters, numbers, and hyphens.
    • The first character must be a letter and the last character cannot be a hyphen.

  5. Click Create.

If you do not have the Yandex Cloud command line interface 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 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:

  • The name must be from 3 to 63 characters long.
  • It may contain lowercase Latin letters, numbers, and hyphens.
  • The first character must be a letter and the last character cannot be 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:

    • The name must be from 3 to 63 characters long.
    • It may contain lowercase Latin letters, numbers, and hyphens.
    • The first character must be a letter and the last character cannot be 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. In 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. Optionally, select Scope. For more information about scopes, see API keys with scope and validity limits.
  8. Optionally, specify Expires at.
  9. Click Create.
  10. Save the ID and secret key.

Alert

After you close the dialog, the key value will become unavailable.

The folder specified in the CLI profile is used by default. 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
Getting a list of supported languages
Next
Overview