[Yandex Cloud documentation](../../index.md) > [Yandex Object Storage](../index.md) > API reference > AWS S3 REST > How to use the API

# How to use the S3 API

## Getting started {#before-you-start}

To authenticate with the [AWS S3 API](api-ref/index.md), you can use:
* [IAM token](../../iam/concepts/authorization/iam-token.md)
* [Static access key](../../iam/concepts/authorization/access-key.md)
* [Temporary Security Token Service keys](../../iam/concepts/authorization/sts.md)
* [Ephemeral access keys](../../iam/concepts/authorization/ephemeral-keys.md)

{% note warning %}

For AWS S3 API, IAM token authentication if the recommended method: it is more secure and, unlike static key authentication, is does not require creating a [request signature](signing-requests.md).

{% endnote %}

To use the API:

{% list tabs group=auth_keys %}


- Authentication with an IAM token {#iam-token}

  1. [Create a service account](../../iam/operations/sa/create.md).
  1. [Assign to the service account the roles](../../iam/operations/sa/assign-role-for-sa.md) required for your project, e.g., [storage.editor](../security/index.md#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](../security/index.md).
      
      To work with objects in an [encrypted](../concepts/encryption.md) bucket, a user or [service account](../../iam/concepts/users/service-accounts.md) must have the following [roles for the encryption key](../../kms/operations/key-access.md) in addition to the `storage.configurer` [role](../security/index.md#storage-configurer):
      
      * `kms.keys.encrypter`: To read the key, [encrypt](../../kms/security/index.md#kms-keys-encrypter) and upload objects.
      * `kms.keys.decrypter`: To read the key, [decrypt](../../kms/security/index.md#kms-keys-decrypter) and download objects.
      * `kms.keys.encrypterDecrypter`: This role includes the `kms.keys.encrypter` and `kms.keys.decrypter` [permissions](../../kms/security/index.md#kms-keys-encrypterDecrypter).
      
      For more information, see [Key Management Service service roles](../../kms/security/index.md#service-roles).

  1. Get an IAM token for the created service account. For more information, see [Getting an IAM token for a service account](../../iam/operations/iam-token/create-for-sa.md).

      {% note tip %}
      
      To quickly get a service account’s IAM token via the [Yandex Cloud CLI](../../cli/index.md), [use impersonation](../../iam/operations/sa/impersonate-sa.md).
      
      {% endnote %}


- Static key authentication {#static-key}

  1. [Create a service account](../../iam/operations/sa/create.md).
  1. [Assign to the service account the roles](../../iam/operations/sa/assign-role-for-sa.md) required for your project, e.g., [storage.editor](../security/index.md#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](../security/index.md).
  
            
      To work with objects in an [encrypted](../concepts/encryption.md) bucket, a user or [service account](../../iam/concepts/users/service-accounts.md) must have the following [roles for the encryption key](../../kms/operations/key-access.md) in addition to the `storage.configurer` [role](../security/index.md#storage-configurer):
      
      * `kms.keys.encrypter`: To read the key, [encrypt](../../kms/security/index.md#kms-keys-encrypter) and upload objects.
      * `kms.keys.decrypter`: To read the key, [decrypt](../../kms/security/index.md#kms-keys-decrypter) and download objects.
      * `kms.keys.encrypterDecrypter`: This role includes the `kms.keys.encrypter` and `kms.keys.decrypter` [permissions](../../kms/security/index.md#kms-keys-encrypterDecrypter).
      
      For more information, see [Key Management Service service roles](../../kms/security/index.md#service-roles).
  
  
  1. [Create a static access key](../../iam/operations/authentication/manage-access-keys.md#create-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](../tools/index.md).
    
  {% note info %}
  
  You can [disable using static keys for bucket access](../operations/buckets/disable-statickey-auth.md). Once disabled, access will be denied to all tools using this access option: the AWS CLI, SDK, and third-party applications. Access via [ephemeral keys](../security/ephemeral-keys.md), [temporary Security Token Service access keys](../security/sts.md), and [pre-signed URLs](../security/overview.md#pre-signed) will also be disabled. Only access with an [IAM token](../../iam/concepts/authorization/iam-token.md) or [anonymous access](../security/public-access.md) (if enabled) will remain.
  
  {% endnote %}
  
  
  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](../tutorials/static-key-in-lockbox/index.md).

{% endlist %}

For a list of supported Amazon S3 HTTP API methods, see the [API reference](api-ref/index.md).

## General API request format {#common-request-form}

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

Request_body
```

The request contains an HTTP method, bucket name, and [object key](../concepts/object.md).

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.

### Signing requests {#signing-requests}

{% list tabs group=auth_keys %}


- Authentication with an IAM token {#iam-token}

  If authenticating with the API via an IAM token, you do not have to additionally sign HTTP requests.


- Static key authentication {#static-key}

  When using a static access key to authenticate with the API and accessing 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)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html).

  When using static access key authentication to access the S3 API from Object Storage, we recommend using the [AWS CLI](../tools/aws-cli.md) or [AWS SDK](../tools/sdk/index.md) suitable for your development environment.

  You can test the request and signature generation using the AWS CLI in [debug mode](signing-requests.md#debugging).
  
  To send a [signed request](../api-ref/authentication.md#s3-api-example) to the S3 API, you can use [curl](https://curl.se/).

{% endlist %}

### Request URL {#request-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>`

{% note info %}

For buckets with periods in their names, e.g., `example.ru`, HTTPS is available only with a URL of the `https://storage.yandexcloud.net/<bucket_name>/<object_key>?<request_parameters>` format. For more information, see [Accessing a bucket over HTTPS](../concepts/bucket.md#bucket-https).

{% endnote %}

The URL contains the bucket name, object key, and request parameters. See an example of possible request parameters in the [Get object method description](api-ref/object/get.md).

{% note info %}

If you use the [AWS SDK for .NET](../tools/aws-sdk-net.md), access the `s3.yandexcloud.net` host.

{% endnote %}

## CORS requests {#cors-requests}

[Cross-domain requests](../concepts/cors.md) are available for all API methods used for object management.

To check permissions, CORS sends the [options](api-ref/object/options.md) 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](api-ref/object/options.md#request-headers) must be the same as those of the preflight request.

#### See also {#see-also}

* [Getting started with the AWS S3 API in Yandex Object Storage](s3-api-quickstart.md)

* [Debugging requests using the AWS CLI](signing-requests.md#debugging)

* [Example of sending a signed request using curl](../api-ref/authentication.md#s3-api-example)

* [Code example for generating a signature](../concepts/pre-signed-urls.md#code-examples)