[Yandex Cloud documentation](../../index.md) > [Yandex Object Storage](../index.md) > API reference > API authentication

# Authentication with the Object Storage API

You can use the following types of APIs to work with Object Storage:

* [AWS S3 API](#aws-s3-api)
* [Yandex Cloud gRPC and REST APIs](#yandex-api)

## AWS S3 API {#aws-s3-api}

To authenticate with the [AWS S3 API](../s3/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](../s3/signing-requests.md).

{% endnote %}

{% list tabs group=auth_keys %}


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

  An IAM token can be issued for either a user account or a service account, and any actions using the IAM token are performed on behalf of the account for which the token was issued. However, using a service account to manage buckets and objects is more secure.

  If authenticating with the API via an IAM token, you do not have to additionally [sign](../s3/signing-requests.md) HTTP requests.


- Static key authentication {#static-key}

  To authenticate with the [AWS S3 API](../s3/api-ref/index.md) and use Terraform and other [supported tools](../tools/index.md), a [static access key](../../iam/concepts/authorization/access-key.md) can be used. A static access key is issued for a specific [service account](../../iam/concepts/users/service-accounts.md), and all actions involving this key are performed on behalf of this service account. For more information, see [How do I use the S3 API?](../s3/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).


  To use the AWS S3 API with authentication via a static access key directly (without an SDK or apps), you will need to [sign requests](../s3/signing-requests.md) yourself. You can test the request and signature generation using the AWS CLI in [debug mode](../s3/signing-requests.md#debugging).

{% endlist %}

For the full list of S3 API methods, see the [S3 API reference](../s3/api-ref/index.md).

{% note info %}

A service account is only allowed to view a list of buckets in the folder it was created in.

A service account can perform actions with objects in buckets that are created in folders different from the service account folder. To enable this, [assign](../../iam/operations/sa/assign-role-for-sa.md) the service account [roles](../security/index.md#service-roles) for the appropriate folder or its bucket.

{% endnote %}

### AWS S3 API use case {#s3-api-example}

{% note warning %}

Make sure the account you are using to make the request has the permissions to perform the requested action. For example, to upload an object to a bucket, [assign](../../iam/operations/sa/assign-role-for-sa.md) the `storage.uploader` [role](../security/index.md#storage-uploader) for the bucket to the account. For more information, see [Access management methods in Object Storage: Overview](../security/overview.md).

{% endnote %}

Below are examples of requests for uploading an object to a bucket:

{% list tabs group=auth_keys %}


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

  ```bash
  IAM_TOKEN="<IAM_token_contents>"
  BUCKET_NAME="<bucket_name>"
  LOCAL_FILE="<local_file_path>"
  OBJECT_PATH="<object_key>"

  curl \
    --request PUT \
    --header "Authorization: Bearer ${IAM_TOKEN}" \
    --upload-file "${LOCAL_FILE}" \
    --verbose \
    "https://storage.yandexcloud.net/${BUCKET_NAME}/${OBJECT_PATH}"
  ```

  Where:

  * `IAM_TOKEN`: IAM token body.
  * `BUCKET_NAME`: [Name of the bucket](../concepts/bucket.md#naming) to upload the file to.
  * `LOCAL_FILE`: Path to the local file you want to upload to the bucket, e.g., `./sample.txt`.
  * `OBJECT_PATH`: [Key](../concepts/object.md#key) to assign to the object in the bucket, e.g., `new-prefix/sample-object.txt`.

  In the same way, you can upload a file to the bucket without saving it locally. For example, archive the directory and send the archive to the bucket:

  ```bash
  IAM_TOKEN="<IAM_token_contents>"
  BUCKET_NAME="<bucket_name>"
  OBJECT_PATH="<object_key>"
  DIRECTORY_PATH="<path_to_directory>"

  tar -cvzf - "${DIRECTORY_PATH}" | curl \
    --request PUT \
    --header "Authorization: Bearer ${IAM_TOKEN}" \
    --upload-file - \
    --verbose \
    "https://storage.yandexcloud.net/${BUCKET_NAME}/${OBJECT_PATH}"
  ```

  Where `DIRECTORY_PATH` is the path to the directory you want to archive.


- Static key authentication {#static-key}

  Starting from version [8.3.0](https://curl.se/changes.html), the `curl` utility supports automatic generation of the [signature string](../s3/signing-requests.md#string-to-sign-gen), [request signing](../s3/signing-requests.md#signing), and substitution of the required headers when working with the AWS S3 API.

  You can also generate these headers and sign requests manually. For more information, see the example for **curl 8.2.1 and lower**.

  {% cut "curl 8.3.0 and higher" %}

  ```bash
  AWS_KEY_ID="<static_key_ID>"
  AWS_SECRET_KEY="<secret_key>"
  LOCAL_FILE="<local_file_path>"
  BUCKET_NAME="<bucket_name>"
  OBJECT_PATH="<object_key>"

  curl \
    --request PUT \
    --user "${AWS_KEY_ID}:${AWS_SECRET_KEY}" \
    --aws-sigv4 "aws:amz:ru-central1:s3" \
    --upload-file "${LOCAL_FILE}" \
    --verbose \
    "https://storage.yandexcloud.net/${BUCKET_NAME}/${OBJECT_PATH}"
  ```

  Where:
  * `AWS_KEY_ID`: Static access key [ID](../../iam/concepts/authorization/access-key.md#key-id).
  * `AWS_SECRET_KEY`: [Secret key](../../iam/concepts/authorization/access-key.md#private-key).
  * `LOCAL_FILE`: Path to the local file you want to upload, e.g., `./sample.txt`.
  * `BUCKET_NAME`: [Name of the bucket](../concepts/bucket.md#naming) to upload the file to.
  * `OBJECT_PATH`: [Key](../concepts/object.md#key) to assign to the object in the bucket, e.g., `new-prefix/sample-object.txt`.

  In the same way, you can upload a file to the bucket without saving it locally. For example, archive the directory and send the archive to the bucket:

  ```bash
  AWS_KEY_ID="<static_key_ID>"
  AWS_SECRET_KEY="<secret_key>"
  BUCKET_NAME="<bucket_name>"
  OBJECT_PATH="<object_key>"
  DIRECTORY_PATH="<path_to_directory>"

  tar -cvzf - "${DIRECTORY_PATH}" | curl \
    --request PUT \
    --user "${AWS_KEY_ID}:${AWS_SECRET_KEY}" \
    --aws-sigv4 "aws:amz:ru-central1:s3" \
    --upload-file - \
    --verbose \
    "https://storage.yandexcloud.net/${BUCKET_NAME}/${OBJECT_PATH}"
  ```

  Where `DIRECTORY_PATH` is the path to the directory you want to archive.

  {% endcut %}

  {% cut "curl 8.2.1 and lower" %}

  ```bash
  AWS_KEY_ID="<static_key_ID>"
  AWS_SECRET_KEY="<secret_key>"
  LOCAL_FILE="<local_file_path>"
  BUCKET_NAME="<bucket_name>"
  OBJECT_PATH="<object_key>"
  CONTENT_TYPE="<object_MIME_type>"
  DATE_VALUE=`date -R`
  STRING_TO_SIGN="PUT\n\n${CONTENT_TYPE}\n${DATE_VALUE}\n/${BUCKET_NAME}/${OBJECT_PATH}"
  SIGNATURE=`echo -en ${STRING_TO_SIGN} | openssl sha1 -hmac ${AWS_SECRET_KEY} -binary | base64`

  curl \
    --request PUT \
    --upload-file "${LOCAL_FILE}" \
    --verbose \
    --header "Host: storage.yandexcloud.net" \
    --header "Date: ${DATE_VALUE}" \
    --header "Content-Type: ${CONTENT_TYPE}" \
    --header "Authorization: AWS ${AWS_KEY_ID}:${SIGNATURE}" \
    "https://storage.yandexcloud.net/${BUCKET_NAME}/${OBJECT_PATH}"
  ```

  Where:
  * `AWS_KEY_ID`: Static access key [ID](../../iam/concepts/authorization/access-key.md#key-id).
  * `AWS_SECRET_KEY`: [Secret key](../../iam/concepts/authorization/access-key.md#private-key).
  * `LOCAL_FILE`: Path to the local file you want to upload, e.g., `./sample.txt`.
  * `BUCKET_NAME`: [Name of the bucket](../concepts/bucket.md#naming) to upload the file to.
  * `OBJECT_PATH`: [Key](../concepts/object.md#key) to assign to the object in the bucket, e.g., `new-prefix/sample-object.txt`.
  * `CONTENT_TYPE`: [MIME type](https://en.wikipedia.org/wiki/Media_type) of the object being uploaded, e.g., `text/plain`.

  {% endcut %}

{% endlist %}

## Yandex Cloud gRPC and REST APIs {#yandex-api}


For authentication in the Yandex Cloud gRPC and REST APIs, get an [IAM token](../../iam/concepts/authorization/iam-token.md). Learn more about getting an IAM token for different account types:

* [Yandex account](../../iam/operations/iam-token/create.md)
* [Federated account](../../iam/operations/iam-token/create-for-federation.md)
* [Service account](../../iam/operations/iam-token/create-for-sa.md)

Specify the received IAM token when accessing Yandex Cloud resources via the API. Provide the IAM token in the `Authorization` header in the following format:

```yaml
Authorization: Bearer <IAM_token>
```

If you have saved your IAM token to a variable, use the latter:

```yaml
Authorization: Bearer ${IAM_TOKEN}
```


For the full list of Yandex Cloud API calls and methods, see the [gRPC API](grpc/index.md) and [REST API](index.md) references.

### Yandex Cloud API use case {#example}

In this example, we will create a 50 GB bucket with a standard storage class.

{% list tabs group=instructions %}

- gRPC API {#grpc-api}

  ```bash
  export IAM_TOKEN="<IAM_token>"
  grpcurl \
    -H "Authorization: Bearer $IAM_TOKEN" \
    -d '{
      "name": "<bucket_name>",
      "folder_id": "<folder_ID>",
      "default_storage_class": "STANDARD",
      "max_size": "53687091200",
      "anonymous_access_flags": [{
        "read": false,
        "list": false,
        "configRead": false
      }]
    }' \
    storage.api.cloud.yandex.net:443 \
    yandex.cloud.storage.v1.BucketService/Create
  ```

  Where:

  * `IAM_TOKEN`: IAM token. See [Getting an IAM token](../../iam/operations/index.md#authentication) for details.
  * `name`: Bucket name.
  * `folder_id`: Folder [ID](../../resource-manager/operations/folder/get-id.md).
  * `default_storage_class`: Storage [class](../concepts/storage-class.md).
  * `max_size`: Bucket size.
  * `anonymous_access_flags`: Bucket [access](../concepts/bucket.md#bucket-access) settings:
    * `read`: Public read access to objects.
    * `list`: Public access to the list of objects.
    * `configRead`: Public read access to settings.

  Result:

  ```text
  {
    "id": "e3ehmmasama1********",
    "description": "create bucket",
    "createdAt": "2023-08-10T06:32:19.836842Z",
    "createdBy": "ajego134p5h1********",
    "modifiedAt": "2023-08-10T06:32:19.836842Z",
    "done": true,
    "metadata": {"@type":"type.googleapis.com/yandex.cloud.storage.v1.CreateBucketMetadata","name":"<bucket_name>"},
    "response": {"@type":"type.googleapis.com/yandex.cloud.storage.v1.Bucket","acl":{},"anonymousAccessFlags":{"read":false,"list":false},"createdAt":"2023-08-10T06:32:17.557756Z","defaultStorageClass":"STANDARD","folderId":"b1gmit33ngp3********","maxSize":"53687091200","name":"<bucket_name>","versioning":"VERSIONING_DISABLED"}
  }
  ```


- REST API {#api}

  ```bash
  export IAM_TOKEN="<IAM_token>"
  curl \
    --request POST \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --data '{
      "name": "<bucket_name>",
      "folderId": "<folder_ID>",
      "defaultStorageClass": "STANDARD",
      "maxSize": "53687091200",
      "anonymousAccessFlags": {
        "read": false,
        "list": false,
        "configRead": false
      }
    }' \
    https://storage.api.cloud.yandex.net/storage/v1/buckets
  ```

  Where:

  * `IAM_TOKEN`: IAM token. See [Getting an IAM token](../../iam/operations/index.md#authentication) for details.
  * `name`: Bucket name.
  * `folderId`: Folder [ID](../../resource-manager/operations/folder/get-id.md).
  * `default_storage_class`: Storage [class](../concepts/storage-class.md).
  * `maxSize`: Bucket size.
  * `anonymousAccessFlags`: Bucket [access](../concepts/bucket.md#bucket-access) settings:
    * `read`: Public read access to objects.
    * `list`: Public access to the list of objects.
    * `configRead`: Public read access to settings.

  Result:

  ```text
  {
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/yandex.cloud.storage.v1.CreateBucketMetadata",
    "name": "<bucket_name>"
  },
  "response": {
    "@type": "type.googleapis.com/yandex.cloud.storage.v1.Bucket",
    "anonymousAccessFlags": {
    "read": false,
    "list": false
    },
    "acl": {},
    "name": "<bucket_name>",
    "folderId": "b1gmit33ngp3********",
    "defaultStorageClass": "STANDARD",
    "versioning": "VERSIONING_DISABLED",
    "maxSize": "53687091200",
    "createdAt": "2023-08-08T12:54:29.321021Z"
  },
  "id": "e3enrkcct2pt********",
  "description": "create bucket",
  "createdAt": "2023-08-08T12:54:32.111022Z",
  "createdBy": "ajego134p5h1********",
  "modifiedAt": "2023-08-08T12:54:32.111022Z"
  }
  ```


{% endlist %}

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

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