How to use the S3 API

Getting startedGetting started

To use the API:

1. Create a service account.

2. Assign to the service account the roles required for your project, e.g., storage.editor for a bucket (to work with a particular bucket) or a folder (to work with all buckets in this folder). For more information about roles, see Access management with Yandex Identity and Access Management.

   To work with objects in an encrypted bucket, a user or service account must have the following roles for the encryption key in addition to the storage.configurer role:

   • kms.keys.encrypter: To read the key, encrypt and upload objects.
   • kms.keys.decrypter: To read the key, decrypt and download objects.
   • kms.keys.encrypterDecrypter: This role includes the kms.keys.encrypter and kms.keys.decrypter permissions.

   For more information, see Key Management Service service roles.

3. Create a static access key.

   As a result, you will get the static access key data. To authenticate in Object Storage, you will need the following:

   • key_id: Static access key ID
   • secret: Secret key

   Save key_id and secret: you will not be able to get the key value again.

To access the HTTP API directly, you need static key authentication, which is supported by the tools listed in Supported tools.

You can use Yandex Lockbox to safely store the static key for access to Object Storage. For more information, see Using a Yandex Lockbox secret to store a static access key.

For a list of supported Amazon S3 HTTP API methods, see the API reference.

General API request formatGeneral API request format

The general Object Storage API request format is as follows:

{GET|HEAD|PUT|DELETE} /<bucket_name>/<object_key> HTTP/2
Host: storage.yandexcloud.net
Content-Length: length
Date: date
Authorization: authorization string (AWS Signature Version 4)

Request_body

The request contains an HTTP method, bucket name, and object key.

The bucket name can be specified as part of the host name. In this case, the request will be as follows:

{GET|HEAD|PUT|DELETE} /<object_key> HTTP/2
Host: <bucket_name>.storage.yandexcloud.net
...

The set of headers is request-specific and described in the documentation for the relevant request.

When using the API directly (without an SDK or apps), you need to generate the Authorization header yourself for signing requests. Find out how to do this in the Amazon S3 documentation: Authenticating Requests (AWS Signature Version 4).

You can test the request and signature generation using the AWS CLI in debug mode.

To send a signed request to the S3 API, you can use curl.

Request URLRequest URL

URLs can have the following formats:

• http(s)://storage.yandexcloud.net/<bucket_name>/<object_key>?<request_parameters>
• http(s)://<bucket_name>.storage.yandexcloud.net/<object_key>?<request_parameters>

The URL contains the bucket name, object key, and request parameters. See an example of possible request parameters in the Get object method description.

CORS requestsCORS requests

Cross-domain requests are available for all API methods used for object management.

To check permissions, CORS sends the options preflight request to the resource. Object Storage allows you to skip the preflight request when sending cross-domain requests to resources. In this case, your request's headers must be the same as those of the preflight request.

See alsoSee also

• Debugging requests using the AWS CLI
• Example of sending a signed request using curl
• Code example for generating a signature