Setting up access with API keys
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:
- Prepare your cloud.
- Create a service account.
- Assign roles to the service account.
- Create an API key.
Prepare your cloud
Sign up for Yandex Cloud and create a billing account:
- Go to the management console
and log in to Yandex Cloud or create an account if you do not have one yet. - On the Yandex Cloud Billing
page, make sure you have a billing account linked and it has theACTIVE
orTRIAL_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
Learn more about clouds and folders.
Create a service account
-
In the management console
, select the folder where you want to create a service account. -
In the Service accounts tab, click Create service account.
-
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.
-
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
- On the management console home page
, select a folder. - Click the Access permissions tab.
- Find the
sa-api
account in the list and click . - Click Edit roles.
- Click Add role in the dialog box that opens and select the
ai.translate.user
role for Yandex Translate orai.vision.user
for Yandex Vision OCR. - 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 orai.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
- In the management console
, navigate to the folder the service account belongs to. - At the top of the screen, go to the Service accounts tab.
- Choose a service account and click the row with its name. Create a new service account if needed.
- In the top panel, click
Create new key and select Create API key. - Enter a description of the key so that you can easily find it in the management console.
- (Optional) Select Scope.
- (Optional) Specify Expires at.
- Click Create.
- Save the ID and private key.
Alert
After you close the dialog, the private 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.
-
See the description of the create API key command:
yc iam api-key create --help
-
Select a service account, e.g.,
sa-api
:yc iam service-account list
Result:
+----------------------+------------------+-------------------------------+ | ID | NAME | DESCRIPTION | +----------------------+------------------+-------------------------------+ | aje6o61dvog2******** | sa-api | | +----------------------+------------------+-------------------------------+
-
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 the 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>