AllCopyObject requests must be authenticated and signed by using IAM credentials (access key ID and secret access key for the IAM identities). All headers with thex-amz- prefix, includingx-amz-copy-source, must be signed. For more information, seeREST Authentication.

Directory buckets - You must use the IAM credentials to authenticate and authorize your access to theCopyObject API operation, instead of using the temporary security credentials through theCreateSession API operation.

AWS CLI or SDKs handles authentication and authorization on your behalf.

You must haveread access to the source object andwrite access to the destination bucket.

When the request is an HTTP 1.1 request, the response is chunk encoded. When the request is not an HTTP 1.1 request, the response would not contain theContent-Length. You always need to read the entire response body to check if the copy succeeds.

The copy request charge is based on the storage class and Region that you specify for the destination object. The request can also result in a data retrieval charge for the source if the source storage class bills for data retrieval. If the copy source is in a different region, the data transfer is billed to the copy source account. For pricing information, seeAmazon S3 pricing.

The name of the destination bucket.

Directory buckets - When you use this operation with a directory bucket, you must use virtual-hosted-style requests in the formatBucket-name.s3express-zone-id.region-code.amazonaws.com. Path-style requests are not supported. Directory bucket names must be unique in the chosen Zone (Availability Zone or Local Zone). Bucket names must follow the formatbucket-base-name--zone-id--x-s3 (for example,amzn-s3-demo-bucket--usw2-az1--x-s3). For information about bucket naming restrictions, seeDirectory bucket naming rules in theAmazon S3 User Guide.

Access points - When you use this action with an access point for general purpose buckets, you must provide the alias of the access point in place of the bucket name or specify the access point ARN. When you use this action with an access point for directory buckets, you must provide the access point name in place of the bucket name. When using the access point ARN, you must direct requests to the access point hostname. The access point hostname takes the formAccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this action with an access point through the AWS SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, seeUsing access points in theAmazon S3 User Guide.

S3 on Outposts - When you use this action with S3 on Outposts, you must use the Outpost bucket access point ARN or the access point alias for the destination bucket. You can only copy objects within the same Outpost bucket. It's not supported to copy objects across different AWS Outposts, between buckets on the same Outposts, or between Outposts buckets and any other bucket types. For more information about S3 on Outposts, seeWhat is S3 on Outposts? in theS3 on Outposts guide. When you use this action with S3 on Outposts through the REST API, you must direct requests to the S3 on Outposts hostname, in the formatAccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. The hostname isn't required when you use the AWS CLI or SDKs.

Required: Yes

Specifies the caching behavior along the request/reply chain.

Specifies presentational information for the object. Indicates whether an object should be displayed in a web browser or downloaded as a file. It allows specifying the desired filename for the downloaded file.

Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

The language the content is in.

A standard MIME type that describes the format of the object data.

The date and time at which the object is no longer cacheable.

The key of the destination object.

Length Constraints: Minimum length of 1.

Required: Yes

The canned access control list (ACL) to apply to the object.

When you copy an object, the ACL metadata is not preserved and is set toprivate by default. Only the owner has full access control. To override the default ACL setting, specify a new ACL when you generate a copy request. For more information, seeUsing ACLs.

If the destination bucket that you're copying objects to uses the bucket owner enforced setting for S3 Object Ownership, ACLs are disabled and no longer affect permissions. Buckets that use this setting only acceptPUT requests that don't specify an ACL orPUT requests that specify bucket owner full control ACLs, such as thebucket-owner-full-control canned ACL or an equivalent form of this ACL expressed in the XML format. For more information, seeControlling ownership of objects and disabling ACLs in theAmazon S3 User Guide.

Valid Values:private | public-read | public-read-write | authenticated-read | aws-exec-read | bucket-owner-read | bucket-owner-full-control

Indicates the algorithm that you want Amazon S3 to use to create the checksum for the object. For more information, seeChecking object integrity in theAmazon S3 User Guide.

When you copy an object, if the source object has a checksum, that checksum value will be copied to the new object by default. If theCopyObject request does not include thisx-amz-checksum-algorithm header, the checksum algorithm will be copied from the source object to the destination object (if it's present on the source object). You can optionally specify a different checksum algorithm to use with thex-amz-checksum-algorithm header. Unrecognized or unsupported values will respond with the HTTP status code400 Bad Request.

Valid Values:CRC32 | CRC32C | SHA1 | SHA256 | CRC64NVME

Specifies the source object for the copy operation. The source object can be up to 5 GB. If the source object is an object that was uploaded by using a multipart upload, the object copy will be a single part object after the source object is copied to the destination bucket.

You specify the value of the copy source in one of two formats, depending on whether you want to access the source object through anaccess point:

If your source bucket versioning is enabled, thex-amz-copy-source header by default identifies the current version of an object to copy. If the current version is a delete marker, Amazon S3 behaves as if the object was deleted. To copy a different version, use theversionId query parameter. Specifically, append?versionId=<version-id> to the value (for example,awsexamplebucket/reports/january.pdf?versionId=QUpfdndhfd8438MNFDN93jdnJFkdmqnh893). If you don't specify a version ID, Amazon S3 copies the latest version of the source object.

If you enable versioning on the destination bucket, Amazon S3 generates a unique version ID for the copied object. This version ID is different from the version ID of the source object. Amazon S3 returns the version ID of the copied object in thex-amz-version-id response header in the response.

If you do not enable versioning or suspend it on the destination bucket, the version ID that Amazon S3 generates in thex-amz-version-id response header is always null.

Pattern:\/?.+\/.+

Required: Yes

Copies the object if its entity tag (ETag) matches the specified tag.

If both thex-amz-copy-source-if-match andx-amz-copy-source-if-unmodified-since headers are present in the request and evaluate as follows, Amazon S3 returns200 OK and copies the data:

Copies the object if it has been modified since the specified time.

If both thex-amz-copy-source-if-none-match andx-amz-copy-source-if-modified-since headers are present in the request and evaluate as follows, Amazon S3 returns the412 Precondition Failed response code:

Copies the object if its entity tag (ETag) is different than the specified ETag.

If both thex-amz-copy-source-if-none-match andx-amz-copy-source-if-modified-since headers are present in the request and evaluate as follows, Amazon S3 returns the412 Precondition Failed response code:

Copies the object if it hasn't been modified since the specified time.

If both thex-amz-copy-source-if-match andx-amz-copy-source-if-unmodified-since headers are present in the request and evaluate as follows, Amazon S3 returns200 OK and copies the data:

Specifies the algorithm to use when decrypting the source object (for example,AES256).

If the source object for the copy is stored in Amazon S3 using SSE-C, you must provide the necessary encryption information in your request so that Amazon S3 can decrypt the object for copying.

Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be the same one that was used when the source object was created.

If the source object for the copy is stored in Amazon S3 using SSE-C, you must provide the necessary encryption information in your request so that Amazon S3 can decrypt the object for copying.

Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

If the source object for the copy is stored in Amazon S3 using SSE-C, you must provide the necessary encryption information in your request so that Amazon S3 can decrypt the object for copying.

The account ID of the expected destination bucket owner. If the account ID that you provide does not match the actual owner of the destination bucket, the request fails with the HTTP status code403 Forbidden (access denied).

Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.

Allows grantee to read the object data and its metadata.

Allows grantee to read the object ACL.

Allows grantee to write the ACL for the applicable object.

Specifies whether the metadata is copied from the source object or replaced with metadata that's provided in the request. When copying an object, you can preserve all metadata (the default) or specify new metadata. If this header isn’t specified,COPY is the default behavior.

General purpose bucket - For general purpose buckets, when you grant permissions, you can use thes3:x-amz-metadata-directive condition key to enforce certain metadata behavior when objects are uploaded. For more information, seeAmazon S3 condition key examples in theAmazon S3 User Guide.

Valid Values:COPY | REPLACE

Specifies whether you want to apply a legal hold to the object copy.

Valid Values:ON | OFF

The Object Lock mode that you want to apply to the object copy.

Valid Values:GOVERNANCE | COMPLIANCE

The date and time when you want the Object Lock of the object copy to expire.

Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. If either the source or destination S3 bucket has Requester Pays enabled, the requester will pay for corresponding charges to copy the object. For information about downloading objects from Requester Pays buckets, seeDownloading Objects in Requester Pays Buckets in theAmazon S3 User Guide.

Valid Values:requester

The server-side encryption algorithm used when storing this object in Amazon S3. Unrecognized or unsupported values won’t write a destination object and will receive a400 Bad Request response.

Amazon S3 automatically encrypts all new objects that are copied to an S3 bucket. When copying an object, if you don't specify encryption information in your copy request, the encryption setting of the target object is set to the default encryption configuration of the destination bucket. By default, all buckets have a base level of encryption configuration that uses server-side encryption with Amazon S3 managed keys (SSE-S3). If the destination bucket has a different default encryption configuration, Amazon S3 uses the corresponding encryption key to encrypt the target object copy.

With server-side encryption, Amazon S3 encrypts your data as it writes your data to disks in its data centers and decrypts the data when you access it. For more information about server-side encryption, seeUsing Server-Side Encryption in theAmazon S3 User Guide.

General purpose buckets

Directory buckets

Valid Values:AES256 | aws:fsx | aws:kms | aws:kms:dsse

Specifies the AWS KMS key ID (Key ID, Key ARN, or Key Alias) to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if they're not made via SSL or using SigV4. For information about configuring any of the officially supported AWS SDKs and AWS CLI, seeSpecifying the Signature Version in Request Authentication in theAmazon S3 User Guide.

Directory buckets - To encrypt data using SSE-KMS, it's recommended to specify thex-amz-server-side-encryption header toaws:kms. Then, thex-amz-server-side-encryption-aws-kms-key-id header implicitly uses the bucket's default KMS customer managed key ID. If you want to explicitly set the x-amz-server-side-encryption-aws-kms-key-id header, it must match the bucket's default customer managed key (using key ID or ARN, not alias). Your SSE-KMS configuration can only support 1customer managed key per directory bucket's lifetime. TheAWS managed key (aws/s3) isn't supported. Incorrect key specification results in an HTTP400 Bad Request error.

Specifies whether Amazon S3 should use an S3 Bucket Key for object encryption with server-side encryption using AWS Key Management Service (AWS KMS) keys (SSE-KMS). If a target object uses SSE-KMS, you can enable an S3 Bucket Key for the object.

Setting this header totrue causes Amazon S3 to use an S3 Bucket Key for object encryption with SSE-KMS. Specifying this header with a COPY action doesn’t affect bucket-level settings for S3 Bucket Key.

For more information, seeAmazon S3 Bucket Keys in theAmazon S3 User Guide.

Specifies the AWS KMS Encryption Context as an additional encryption context to use for the destination object encryption. The value of this header is a base64-encoded UTF-8 string holding JSON with the encryption context key-value pairs.

General purpose buckets - This value must be explicitly added to specify encryption context forCopyObject requests if you want an additional encryption context for your destination object. The additional encryption context of the source object won't be copied to the destination object. For more information, seeEncryption context in theAmazon S3 User Guide.

Directory buckets - You can optionally provide an explicit encryption context value. The value must match the default encryption context - the bucket Amazon Resource Name (ARN). An additional encryption context value is not supported.

Specifies the algorithm to use when encrypting the object (for example,AES256).

When you perform aCopyObject operation, if you want to use a different type of encryption setting for the target object, you can specify appropriate encryption-related headers to encrypt the target object with an Amazon S3 managed key, a KMS key, or a customer-provided key. If the encryption setting in your request is different from the default encryption configuration of the destination bucket, the encryption setting in your request takes precedence.

Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded. Amazon S3 does not store the encryption key. The key must be appropriate for use with the algorithm specified in thex-amz-server-side-encryption-customer-algorithm header.

Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

The account ID of the expected source bucket owner. If the account ID that you provide does not match the actual owner of the source bucket, the request fails with the HTTP status code403 Forbidden (access denied).

If thex-amz-storage-class header is not used, the copied object will be stored in theSTANDARD Storage Class by default. TheSTANDARD storage class provides high durability and high availability. Depending on performance needs, you can specify a different Storage Class.

You can use theCopyObject action to change the storage class of an object that is already stored in Amazon S3 by using thex-amz-storage-class header. For more information, seeStorage Classes in theAmazon S3 User Guide.

Before using an object as a source object for the copy operation, you must restore a copy of it if it meets any of the following conditions:

For more information, seeRestoreObject andCopying Objects in theAmazon S3 User Guide.

Valid Values:STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE | OUTPOSTS | GLACIER_IR | SNOW | EXPRESS_ONEZONE | FSX_OPENZFS

The tag-set for the object copy in the destination bucket. This value must be used in conjunction with thex-amz-tagging-directive if you chooseREPLACE for thex-amz-tagging-directive. If you chooseCOPY for thex-amz-tagging-directive, you don't need to set thex-amz-tagging header, because the tag-set will be copied from the source object directly. The tag-set must be encoded as URL Query parameters.

The default value is the empty value.

Specifies whether the object tag-set is copied from the source object or replaced with the tag-set that's provided in the request.

The default value isCOPY.

Valid Values:COPY | REPLACE

If the destination bucket is configured as a website, redirects requests for this object copy to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata. This value is unique to each object and is not copied when using thex-amz-metadata-directive header. Instead, you may opt to provide this header in combination with thex-amz-metadata-directive header.

Version ID of the source object that was copied.

If the object expiration is configured, the response includes this header.

If present, indicates that the requester was successfully charged for the request. For more information, seeUsing Requester Pays buckets for storage transfers and usage in theAmazon Simple Storage Service user guide.

Valid Values:requester

The server-side encryption algorithm used when you store this object in Amazon S3 or Amazon FSx.

Valid Values:AES256 | aws:fsx | aws:kms | aws:kms:dsse

If present, indicates the ID of the KMS key that was used for object encryption.

Indicates whether the copied object uses an S3 Bucket Key for server-side encryption with AWS Key Management Service (AWS KMS) keys (SSE-KMS).

If present, indicates the AWS KMS Encryption Context to use for object encryption. The value of this header is a Base64 encoded UTF-8 string holding JSON with the encryption context key-value pairs.

If server-side encryption with a customer-provided encryption key was requested, the response will include this header to confirm the encryption algorithm that's used.

If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide the round-trip message integrity verification of the customer-provided encryption key.

Version ID of the newly created copy.

Root level tag for the CopyObjectResult parameters.

Required: Yes

The Base64 encoded, 32-bitCRC32 checksum of the object. This checksum is only present if the object was uploaded with the object. For more information, see Checking object integrity in theAmazon S3 User Guide.

Type: String

The Base64 encoded, 32-bitCRC32C checksum of the object. This will only be present if the object was uploaded with the object. For more information, see Checking object integrity in theAmazon S3 User Guide.

Type: String

The Base64 encoded, 64-bitCRC64NVME checksum of the object. This checksum is present if the object being copied was uploaded with theCRC64NVME checksum algorithm, or if the object was uploaded without a checksum (and Amazon S3 added the default checksum,CRC64NVME, to the uploaded object). For more information, seeChecking object integrity in theAmazon S3 User Guide.

Type: String

The Base64 encoded, 160-bitSHA1 digest of the object. This will only be present if the object was uploaded with the object. For more information, see Checking object integrity in theAmazon S3 User Guide.

Type: String

The Base64 encoded, 256-bitSHA256 digest of the object. This will only be present if the object was uploaded with the object. For more information, see Checking object integrity in theAmazon S3 User Guide.

Type: String

The checksum type that is used to calculate the object’s checksum value. For more information, seeChecking object integrity in theAmazon S3 User Guide.

Type: String

Valid Values:COMPOSITE | FULL_OBJECT

Returns the ETag of the new object. The ETag reflects only changes to the contents of an object, not its metadata.

Type: String

Creation date of the object.

Type: Timestamp

The source object of the COPY action is not in the active tier and is only stored in Amazon S3 Glacier.

HTTP Status Code: 403