Using Pre-Authenticated Requests

$ curl -X PUT --data-binary '@<local-filename>' <unique-PAR-URL>

For example:

$ curl -X PUT --data-binary '@using-dita-guide.pdf' https://objectstorage.us-phoenix-1.oraclecloud.com/p/j3DoSvgQHbUaw6ADzHkDlnaqMuXWef_lhTxCiS9ngCw/n/MyNamespace/b/MyParBucket/o/using-dita-guide.pdf

You can also provide custom metadata for any object using opc-meta-<name>:<value> headers.

$ curl -X PUT -H "opc-meta-<name>:<value>" --data-binary '@<local-filename>' <unique-PAR-URL>

For example:

$ curl -X PUT -H "opc-meta-version:2020May" PUT --data-binary '@CorporateTerminologyUsageGuide.pdf' https://objectstorage.us-phoenix-1.oraclecloud.com/p/71LzRt_V8LVT7BVLbeQOB5KAx67AxzeKXwJ8mIA5dN0WheYH39a7KiY2UXnUBhaX/n/MyNamespace/b/MyParBucket/o/CorporateTerminologyUsageGuide.pdf

Multipart uploads accommodate objects that are too large for a single upload operation. We recommend that you use multipart uploads to upload objects larger than 100 MiB. The maximum size for an uploaded object is 10 TiB. Object parts must be no larger than 50 GiB. Using multipart uploads, you have the flexibility of pausing between the uploads of individual parts, and resuming the upload when your schedule and resources allow.

Step 1: To direct Object Storage to create a multipart upload, you simply include the header opc-multipart: true in the PUT command.

$ curl -X PUT -H "opc-multipart:true" <unique-PAR-URL>

For example:

$ curl -X PUT -H "opc-multipart:true" https://objectstorage.us-phoenix-1.oraclecloud.com/p/j3DoSvgQHbUaw6ADzHkDlnaqMuXWef_lhTxCiS9ngCw/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf

{"namespace":"MyNamespace","bucket":"MyParBucket","object":"OCI_User_Guide.pdf","uploadId":"b5bb4079-9d50-ac59-182e-4d133a962382","timeCreated":"2021-03-05T14:48:53.738Z","storageTier":"Standard","accessUri":"/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/"}

Step 2: Use the access URI together with the Object Storage hostname for the target region to upload parts, specifying the part number at the end of the URI. For example, to upload an object in three parts, issue the following PUT commands:

$ curl -X PUT --data-binary '@data.1' https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/1
$ curl -X PUT --data-binary '@data.2' https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/2
$ curl -X PUT --data-binary '@data.3' https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/3

Step 3: To commit the multipart upload, use the POST command with the access URI. For example:

$ curl -X POST https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/

You can delete all parts of an uncommitted or failed multipart upload using the DELETE command with the access URI. For example:

$ curl -X DELETE https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/

You can also provide custom metadata for any object using opc-meta- headers. The "-H opc-meta-<name>:<value>" is only needed on the first pre-authenticated request that creates the multipart upload, not on each individual part. See To put an object with custom metadata for more information.

$ curl -X GET <unique-PAR-URL>

For example:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/MR7rGASetBbu4L1R5ZH91meUZJjVkOGmd4rtnjDhazP9o6s2KzLyFUxILQzSamEp/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf
'@data.1''@data.2''@data.3'

For pre-authenticated requests that apply to multiple objects, the request creator can optionally let you list objects.

$ curl -X GET <unique-PAR-URL>

For example:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/
{"objects":[{"name":"InfoWorld DeepDive - Tips  for Git and GitHub Users.pdf"},{"name":"OCI_User_Guide.pdf"},{"name":"OracleCorporateTerminologyUsageGuideRedwood.pdf"},{"name":"VPN.png"},{"name":"eventslogreference.htm"},{"name":"functionslogreference.htm"},{"name":"glob.txt"},{"name":"loadbalancerreference.htm"},{"name":"objectstoragelogreference.htm"},{"name":"servicechanges.html"},{"name":"servicediscovery.dita"},{"name":"serviceessentials.html"},{"name":"servicelogreference.htm"},{"name":"services.html"},{"name":"udx-1494-lifecycle-rule-glob.pdf"}]}

By default, the object list returns only the names of the objects. Optionally, you can use the fields query parameter to also include the size (object size in bytes), etag, md5, timeCreated (object creation date and time), timeModified (object modification date and time), storageTier, and archivalState fields. Specify the value of this parameter as a comma-separated, case-insensitive list of those field names that you want to include in the object list. For example:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/?fields="name,etag,timeCreated,md5,timeModified,storageTier,archivalState"
{"objects":[{"name":"InfoWorld DeepDive - Tips  for Git and GitHub Users.pdf","timeCreated":"2021-04-01T14:27:13.039Z","timeModified":"2021-04-01T14:27:27.552Z","etag":"e5032a35-07d7-476f-88aa-a95c5d07f0d9","storageTier":"Standard","md5":"3OPjerv2zKJdf9fzFeP9BQ=="},{"name":"OCI_User_Guide.pdf","timeCreated":"2021-04-01T14:27:20.359Z","timeModified":"2021-04-02T23:18:01.299Z","etag":"0dd28308-b821-47e7-9685-111eedef1c5c","storageTier":"Standard","md5":"/2+fTemSy7CsR00OnFK87Q=="},{"name":"OracleCorporateTerminologyUsageGuideRedwood.pdf","timeCreated":"2021-04-01T14:27:12.228Z","timeModified":"2021-04-01T14:27:21.302Z","etag":"1948d01b-9611-4a79-a9dd-f5b24888c0bc","storageTier":"Standard","md5":"JIdR+kCzQNkl0riH08Ktpw=="},{"name":"VPN.png","timeCreated":"2021-04-01T14:27:11.943Z","timeModified":"2021-04-01T14:27:12.047Z","etag":"b4f20050-e268-42e5-8980-29f6a972b6bf","storageTier":"Standard","md5":"aWFjq5fe+hsDT/x5cWhasA=="},{"name":"eventslogreference.htm","timeCreated":"2021-04-01T14:27:10.725Z","timeModified":"2021-04-01T14:27:10.746Z","etag":"84362592-0a18-438d-8773-7dcc702103aa","storageTier":"Standard","md5":"As+3syaEbvMhPm8fM+DSAw=="},{"name":"functionslogreference.htm","timeCreated":"2021-04-01T14:27:10.865Z","timeModified":"2021-04-01T14:27:10.900Z","etag":"4d494efa-5d48-491a-84ba-254be2aa8549","storageTier":"Standard","md5":"lt28WcIiqKklMS5p2LbECQ=="},{"name":"glob.txt","timeCreated":"2021-04-05T16:12:31.925Z","timeModified":"2021-04-05T16:12:31.952Z","etag":"c330ce8c-4c61-4342-9ac5-4bc0fd846944","storageTier":"Standard","md5":"BeMbbI+uOOGzmFA/NXwwxQ=="},{"name":"loadbalancerreference.htm","timeCreated":"2021-04-01T14:27:11.480Z","timeModified":"2021-04-01T14:27:11.574Z","etag":"522a3b1d-f736-4e30-9b5d-feed3867912d","storageTier":"Standard","md5":"u2GP2ngLVEq9xUAykRg2ug=="},{"name":"objectstoragelogreference.htm","timeCreated":"2021-04-01T14:27:11.416Z","timeModified":"2021-04-01T14:27:11.479Z","etag":"fbf7a035-7b80-4c91-a932-53bf0917bef9","storageTier":"Standard","md5":"skstBGw3YcHBomI6X/YwEA=="},{"name":"servicechanges.html","timeCreated":"2021-04-01T14:27:11.702Z","timeModified":"2021-04-01T14:27:11.716Z","etag":"016df222-128d-4e7f-a191-b5c0a5dbc7e0","storageTier":"Standard","md5":"sVzYaODHww3Qw1jwbtj7SA=="},{"name":"servicediscovery.dita","timeCreated":"2021-04-02T17:16:04.134Z","timeModified":"2021-04-02T17:16:04.149Z","etag":"7997226d-e2ba-460a-be75-97436dcb30e8","storageTier":"Standard","md5":"I/ZjF5rcoaJXH6abpbDPag=="},{"name":"serviceessentials.html","timeCreated":"2021-04-01T14:27:11.700Z","timeModified":"2021-04-01T14:27:11.737Z","etag":"687d0914-19c7-4ff6-8ceb-90ab0bbd1fc1","storageTier":"Standard","md5":"HSf0uMVHxFCuVr/I5insxQ=="},{"name":"servicelogreference.htm","timeCreated":"2021-04-01T14:27:11.767Z","timeModified":"2021-04-01T14:27:11.775Z","etag":"240f2d71-da38-461c-a821-506b85b7e6e7","storageTier":"Standard","md5":"jxyWxK9z8OW0zsozadNRkQ=="},{"name":"services.html","timeCreated":"2021-04-01T14:27:11.780Z","timeModified":"2021-04-01T14:27:11.913Z","etag":"6e570928-a5b2-4e49-8e54-22186825350a","storageTier":"Standard","md5":"fDuH2Y7LDAafjlyUCQZohQ=="},{"name":"udx-1494-lifecycle-rule-glob.pdf","timeCreated":"2021-04-01T14:27:12.044Z","timeModified":"2021-04-01T14:27:12.686Z","etag":"a92174a2-cad3-4239-b4c9-48f2abd4dd8c","storageTier":"Standard","md5":"4ltcJZgQ80sNz8RHu7TJlQ=="}]}

In addition to fields, pre-authenticated requests support all other ListObjects query parameters and list pagination.

$ curl --head <unique-PAR-URL>

For example:

$ curl --head https://objectstorage.us-phoenix-1.oraclecloud.com/p/MR7rGASetBbu4L1R5ZH91meUZJjVkOGmd4rtnjDhazP9o6s2KzLyFUxILQzSamEp/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf
HTTP/1.1 200 OK
accept-ranges: bytes
Content-Length: 27
opc-multipart-md5: AgQlttlYM7ya/tH0Fosu9A==-3
last-modified: Fri, 05 Mar 2021 15:15:44 GMT
etag: 9b9093ab-bdc6-49af-b261-b2d1d111d952
version-id: d3346446-e1f3-46e3-97e5-ee3c8e57ee30
storage-tier: Standard
Content-Type: application/x-www-form-urlencoded
date: Thu, 18 Mar 2021 22:11:11 GMT
opc-request-id: phx-1:odm8FLV-LC7yR7sskUL955sjFjOqaKrQ-cO3JbGhSbcwYcovlRa2QtABQPfeW_Q_
x-api-id: native
access-control-allow-origin: *
access-control-allow-methods: POST,PUT,GET,HEAD,DELETE,OPTIONS
access-control-allow-credentials: true
access-control-expose-headers: accept-ranges,access-control-allow-credentials,access-control-allow-methods,access-control-allow-origin,content-length,content-type,date,etag,last-modified,opc-client-info,opc-multipart-md5,opc-request-id,storage-tier,version-id,x-api-id

You can override the response headers in the PAR GET requests by using the following query parameters:

For example:

Default URL (shows inline) - https://objectstorage.us-phoenix-1.oraclecloud.com/p/bDh0EOiY_C0K0NYn8YIhC_fgVOj96BM8S6YApdmlr7pwv4Xuie-6IiLbF1eQdcWi/n/bmcostests/b/bucket-20220302-1236/o/example.txt

Download and save with default filename - https://objectstorage.us-phoenix-1.oraclecloud.com/p/bDh0EOiY_C0K0NYn8YIhC_fgVOj96BM8S6YApdmlr7pwv4Xuie-6IiLbF1eQdcWi/n/bmcostests/b/bucket-20220302-1236/o/example.txt?httpResponseContentDisposition=attachment

Download and save with custom filename - https://objectstorage.us-phoenix-1.oraclecloud.com/p/bDh0EOiY_C0K0NYn8YIhC_fgVOj96BM8S6YApdmlr7pwv4Xuie-6IiLbF1eQdcWi/n/bmcostests/b/bucket-20220302-1236/o/example.txt?httpResponseContentDisposition=attachment%3B%20filename%3Ddownload.txt

1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
2. Choose the compartment where the bucket is.
3. Click the bucket name.
4. Click Pre-Authenticated Requests under Resources to display the list of existing pre-authenticated requests.
5. Click Create Pre-Authenticated Request.
6. Provide the following information:

   • Name: Required. The system automatically generates a default, pre-authenticated request name that reflects the current year, month, day, and time, for example par-bucket-20210330-1643.

     If you change this default name, use only letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.

   • Pre-Authenticated Request Target: Required. Bucket is selected by default, however, you can select a different target.
   • Access Type: Select one of the following types:
     • Permit object reads (the default)
     • Permit object writes
     • Permit object reads and writes
   • Enable Object Listing: Select this option if you want to also let pre-authenticated request users list the objects in the bucket.
   • Expiration: Accept the one week, system-generated expiration date or use the date and time editor to use a different expiration date and time.

7. Click Create Pre-Authenticated Request.

   After a request is created, the Pre-Authenticated Request Details dialog box displays the URL used to access the bucket.

8. Click the copy icon to the right of the URL and paste the URL somewhere in durable storage for future reference.

   Important
   
   The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation, is not stored in Object Storage, and cannot be retrieved later.
9. Click Close.

1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
2. Choose the compartment where the bucket is.

3. Click the bucket name.

4. Click Objects under Resources to display the list of objects.
5. For the object that you want to create a pre-authenticated request, click the Actions menu, and then click Create Pre-Authenticated Request.
6. Provide the following information:

   • Name: Required. The system automatically generates a default, pre-authenticated request name that reflects the current year, month, day, and time, for example par-object-20210330-1654.

     If you change this default name, use only letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.

   • Pre-Authenticated Request Target: Required. Object is selected by default, however, you can select a different target.
   • Object Name: The name of the object that you are creating the pre-authenticated request for is displayed. You cannot change the name of the object.

   • Access Type: Select one of the following types:

     • Permit read on the object
     • Permit writes to the object
     • Permit reads on and writes to the object
   • Expiration: Accept the one week, system-generated expiration date or use the date and time editor to a different expiration date and time.

7. Click Create Pre-Authenticated Request.

   After a request is created, the Pre-Authenticated Request Details dialog box displays the URL used to access the bucket.

8. Click the copy icon to the right of the URL and paste the URL somewhere in durable storage for future reference.

   Important
   
   The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation, is not stored in Object Storage, and cannot be retrieved later.
9. Click Close.

When you create a pre-authenticated request with a prefix, you are limiting the scope of the request to only those objects with that prefix.

1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
2. Choose the compartment where the bucket is.
3. Click the bucket name.
4. Click Pre-Authenticated Requests under Resources to display the list of existing pre-authenticated requests.
5. Click Create Pre-Authenticated Request.
6. Select the required Pre-Authenticated Request Target of Objects with prefix to properly set the context for the other fields in the dialog.
7. Provide the following information:

   • Name: Required. The system automatically generates a default, pre-authenticated request name that reflects the current year, month, day, and time, for example par-object-prefix-20210330-1723.

     If you change this default name, use only letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.

   • Prefix: Required. Prefix string to match on to specify the objects that the pre-authenticated request applies to:
     • You can specify a prefix that includes one or more forward slashes (/) to match on object names that simulate a hierarchy or a directory structure.
     • You can specify a prefix string without a delimiter to match on the left-most characters of the object name.

     See Object Naming Using Prefixes and Hierarchies for details.

   • Access Type: Select one of the following types:
     • Permit object reads (the default)
     • Permit object writes
     • Permit object reads and writes
   • Enable Object Listing: Select this option if you want to also let pre-authenticated request users list the prefixed objects.
   • Expiration: Accept the one week, system-generated expiration date or use the date and time editor to use a different expiration date and time.

8. Click Create Pre-Authenticated Request.

   After a request is created, the Pre-Authenticated Request Details dialog box displays the URL used to access the bucket.

9. Click the copy icon to the right of the URL and paste the URL somewhere in durable storage for future reference.

   Important
   
   

   • The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation, is not stored in Object Storage, and cannot be retrieved later.
   • The URL generated when you create a pre-authenticated request for an object with a prefix does not contain the prefix by default. The user must manually add the prefix to the URL to be able to access the object.
10. Click Close.

To copy the ID for a pre-authenticated request to the clipboard, do the following:

1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
2. Choose the compartment where the bucket is.
3. Click the bucket name.
4. Click Pre-Authenticated Requests under Resources to display the list of pre-authenticated requests.

5. For the pre-authenticated request ID that you want to copy, click the Actions menu, and then click Copy Pre-Authenticated Request ID.

   The ID for the selected pre-authentication request is copied to the clipboard.

oci os preauth-request create --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <preauthenticated_request_name> --access-type <enum_value> --time-expires <timestamp> [--bucket-listing-action ListObjects]

Avoid entering confidential information in the <preauthenticated_request_name>.

The <enum_value> for --access-type is one of the following when creating a pre-authenticated request for all objects in a bucket:

• AnyObjectRead permits reads on all objects in the bucket
• AnyObjectWrite permits writes to all objects in the bucket
• AnyObjectReadWrite permits reads and writes to all objects in the bucket

<timestamp> is required and must be an RFC 3339 timestamp. For example: 2017-09-01T00:09:51.000+02:00.

Listing objects is denied by default. If the --access-type is AnyObjectRead or AnyObjectReadWrite, you can specify the optional --bucket-listing-action ListObjects parameter when creating the pre-authenticated request that lets users list the objects in the bucket.

oci os preauth-request create --namespace MyNamespace --bucket-name MyParBucket --name MyAllObjectsReadWritePAR --access-type AnyObjectReadWrite --time-expires="2022-11-21T23:00:00+00:00" --bucket-listing-action ListObjects
{  "data": {
    "access-type": "AnyObjectReadWrite",
    "access-uri": "/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/",
    "bucket-listing-action": "ListObjects",
    "id": "QgT6f1skUMbXDhpXKQ4BRX9u7ci8AAJ7f9OGzgdEkNJ3XQmHzeN/kDhLEbN2HvPn",
    "name": "MyAllObjectsReadWritePAR",
    "object-name": null,
    "time-created": "2021-04-02T22:25:27.322000+00:00",
    "time-expires": "2022-11-21T23:00:00+00:00"
  }
}

The unique pre-authenticated request URL provided to users for the previous example is constructed as follows:

https://objectstorage.<region_identifier>.oraclecloud.com<access-uri>

See About Regions and Availability Domains for the list of valid region identifiers.

For example, here is the complete URL for the request that allows reads and writes to all objects in the bucket named MyParBucket:

https://objectstorage.us-phoenix-1.oraclecloud.com/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/

Here is an example of using curl to PUT an object using the pre-authenticated request that allows reads and writes to all objects in the bucket named MyParBucket and has listing objects enabled:

$ curl -X PUT --data-binary '@edit-lifecycle-rules.pdf' https://objectstorage.us-phoenix-1.oraclecloud.com/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/edit-lifecycle-rules.pdf

Here is an example of using curl to GET objects using the same pre-authenticated request:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/
{"objects":[{"name":"InfoWorld DeepDive - Tips  for Git and GitHub Users.pdf"},{"name":"OCISG_README.txt"},{"name":"OCI_User_Guide.pdf"},{"name":"OracleCorporateTerminologyUsageGuideRedwood.pdf"},{"name":"VPN.png"},{"name":"eventslogreference.htm"},{"name":"flowlogreference.htm"},{"name":"functionslogreference.htm"},{"name":"glob.txt"},{"name":"loadbalancerreference.htm"},{"name":"objectstoragelogreference.htm"},{"name":"replication.txt"},{"name":"troubleshooting.txt"},{"name":"udx-1494-lifecycle-rule-glob.pdf"}]}

Notice the GET lists the recent PUT for edit-lifecycle-rules.pdf and all other objects in the bucket. Optionally, you can use the fields query parameter to also include the size (object size in bytes), etag, md5, timeCreated (object creation date and time), timeModified (object modification date and time), storageTier, and archivalState fields. See To get a list of objects for more details.

oci os preauth-request create --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <preauthenticated_request_name> --access-type <enum_value> -time-expires <timestamp> --object-name <object_name

Avoid entering confidential information in the pre-authenticated request name.

The <enum_value> for --access-type is one of the following when creating a pre-authenticated request for an object:

• ObjectRead permits object reads
• ObjectWrite permits object writes
• ObjectReadWrite permits both object reads and writes

The <timestamp> is required and must be an RFC 3339 timestamp. For example: 2017-09-01T00:09:51.000+02:00.

oci os preauth-request create --namespace <object_storage_namespace> --bucket-name MyParBucket --name MyObjectReadWritePAR --access-type ObjectReadWrite --object-name OCI_User_Guide.pdf --time-expires="2022-11-21T23:00:00+00:00"
{  "data": {
    "access-type": "ObjectReadWrite",
    "access-uri": "/p/v0YC_6i3NamyrKlIds0SKnWUMQLw_PFolSyGCpjVUJ6h_A1tnkXJ9VRcuQZTgjRa/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf",
    "bucket-listing-action": null,
    "id": "vNObHUdqwf7pfCq9pup/LlMLTLxBt2N2OCKrGwimLFOoJlVfxj/dlESbxyd54vpf:OCI_User_Guide.pdf",
    "name": "MyObjectReadWritePAR",
    "object-name": "OCI_User_Guide.pdf",
    "time-created": "2021-04-01T14:37:26.869000+00:00",
    "time-expires": "2022-11-21T23:00:00+00:00"
  }
}

The unique pre-authenticated request URL provided to users for the previous example is constructed as follows:

https://objectstorage.<region_ID>.oraclecloud.com<access-uri>

For example, here is the complete URL for the request that allows reads and writes to an object named OCI_User_Guide.pdf in the bucket named MyParBucket:

https://objectstorage.us-phoenix-1.oraclecloud.com/p/v0YC_6i3NamyrKlIds0SKnWUMQLw_PFolSyGCpjVUJ6h_A1tnkXJ9VRcuQZTgjRa/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf

Here is an example of using curl to PUT an object using the pre-authenticated request that allows reads and writes to the target object named OCI_User_Guide.pdf in the bucket named MyParBucket:

$ curl -X PUT --data-binary '@OCI_User_Guide.pdf' https://objectstorage.us-phoenix-1.oraclecloud.com/p/v0YC_6i3NamyrKlIds0SKnWUMQLw_PFolSyGCpjVUJ6h_A1tnkXJ9VRcuQZTgjRa/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf

Here is an example of using curl to GET the target object using the same pre-authenticated request:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/v0YC_6i3NamyrKlIds0SKnWUMQLw_PFolSyGCpjVUJ6h_A1tnkXJ9VRcuQZTgjRa/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf
'@OCI_User_Guide.pdf'

When you create a pre-authenticated request with a prefix, you are limiting the scope of the request to only those objects with that prefix.

oci os preauth-request create --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <preauthenticated_request_name> --access-type <enum_value> --object-name="<prefix>" --time-expires <timestamp> [--bucket-listing-action ListObjects]

Avoid entering confidential information in the <preauthenticated_request_name>.

The <enum_value> for --access-type is one of the following when creating a pre-authenticated request for all objects in a bucket:

• AnyObjectRead permits reads on objects with the specified prefix
• AnyObjectWrite permits writes to objects with the specified prefix
• AnyObjectReadWrite permits both reads and writes to objects with the specified prefix

<timestamp> is required and must be an RFC 3339 timestamp. For example: 2017-09-01T00:09:51.000+02:00.

Specify the prefix to match on in the --object-name parameter:

• You can specify a prefix that includes one or more forward slashes (/) to match on object names that simulate a hierarchy or a directory structure.
• You can specify a prefix string without a delimiter to match on the left-most characters of the object name.

Listing objects is denied by default. If the --access-type is AnyObjectRead or AnyObjectReadWrite, you can specify the optional --bucket-listing-action ListObjects parameter when creating the pre-authenticated request that lets users list the objects in the bucket.

oci os preauth-request create --namespace MyNamespace --bucket-name MyParBucket --name PrefixedObjectsReadWritePAR --access-type AnyObjectReadWrite --object-name service --time-expires "2022-11-21T23:00:00+00:00" --bucket-listing-action ListObjects
{  "data": {
    "access-type": "AnyObjectReadWrite",
    "access-uri": "/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/",
    "bucket-listing-action": "ListObjects",
    "id": "YOExDlFsNYBNEwF8Uo4aK8WHiz59enVQm1aID+4cxFobgcaofVbZkg371rxK+6Vb",
    "name": "PrefixedObjectsReadWritePAR",
    "object-name": "service",
    "time-created": "2021-04-01T15:35:40.609000+00:00",
    "time-expires": "2022-11-21T23:00:00+00:00"
  }
}

The unique pre-authenticated request URL provided to users for the previous example is constructed as follows:

https://objectstorage.<region_identifier>.oraclecloud.com<access-uri>

See About Regions and Availability Domains for the list of valid region identifiers.

For example, here is the complete URL for the request that allows reads and writes to objects with the prefix service in the bucket named MyParBucket:

https://objectstorage.us-phoenix-1.oraclecloud.com/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/

When you create a pre-authenticated request that limits the scope to objects with a specific prefix, request users can only GET and PUT objects with the prefix name specified in the request. Trying to GET or PUT an object without or with a different prefix fails.

Here is an example of using curl to PUT an object using the pre-authenticated request that allows reads and writes to objects with the prefix service in the bucket named MyParBucket:

$ curl -X PUT --data-binary '@servicediscovery.dita' https://objectstorage.us-phoenix-1.oraclecloud.com/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/servicediscovery.dita

Here is an example of using curl to GET objects using the same pre-authenticated request:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/
{"objects":[{"name":"servicechanges.html"},{"name":"servicediscovery.dita"},{"name":"serviceessentials.html"},{"name":"servicelogreference.htm"},{"name":"services.html"}]}

Notice the GET lists the recent PUT for servicediscovery.dita and all other objects with a service prefix. Optionally, you can use the fields query parameter to also include the size (object size in bytes), etag, md5, timeCreated (object creation date and time), timeModified (object modification date and time), storageTier, and archivalState fields. See To get a list of objects for more details.

Here is another example of using curl to PUT an object using the same pre-authenticated request. The request fails because the object does not have a service prefix:

$ curl -X PUT --data-binary '@objectstoragelogreference.htm' https://objectstorage.us-phoenix-1.oraclecloud.com/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/objectstoragelogreference.htm
{"code":"NotAuthenticated","message":"PAR does not exist"}

You can list all the pre-authenticated requests that are associated with a particular bucket and the objects in that bucket.

oci os preauth-request list --namespace <object_storage_namespace> --bucket-name <bucket_name>

For example:

oci os preauth-request list --namespace MyNamespace --bucket-name MyParBucket
{
  "data": [
    {
      "access-type": "AnyObjectReadWrite",
      "bucket-listing-action": "ListObjects",
      "id": "1G9pfj8elWI0COPtQUmoQayRmYegDrTWjBskI5BixeGY7k5cPHr1BKdFzgEt3OEG",
      "name": "PrefixedObjectsReadWritePAR",
      "object-name": "service",
      "time-created": "2021-04-02T23:52:21.590000+00:00",
      "time-expires": "2022-11-21T23:00:00+00:00"
    },
    {
      "access-type": "AnyObjectReadWrite",
      "bucket-listing-action": "ListObjects",
      "id": "N5Fim23jXHBnAtWBo7FOCOTdXwAZgXRJD1FoDs1S8BD0qhYegO0eHF5prVkPkiVM",
      "name": "MyAllObjectsReadWritePAR",
      "object-name": null,
      "time-created": "2021-04-01T14:13:59.659000+00:00",
      "time-expires": "2022-11-21T23:00:00+00:00"
    },
    {
      "access-type": "ObjectReadWrite",
      "bucket-listing-action": null,
      "id": "I2Z3qm0rnYiJ5HSTvSCVu8+BqOmy1lXD1dNreBk3eM5VHLdWyIU3xkDTjBqAagoF:OCI_User_Guide.pdf",
      "name": "MyObjectReadWritePAR",
      "object-name": "OCI_User_Guide.pdf",
      "time-created": "2021-04-01T15:27:02.467000+00:00",
      "time-expires": "2022-11-21T23:00:00+00:00"
    },
    {
      "access-type": "AnyObjectReadWrite",
      "bucket-listing-action": "ListObjects",
      "id": "QgT6f1skUMbXDhpXKQ4BRX9u7ci8AAJ7f9OGzgdEkNJ3XQmHzeN/kDhLEbN2HvPn",
      "name": "MyAllObjectsReadWritePAR",
      "object-name": null,
      "time-created": "2021-04-02T22:25:27.322000+00:00",
      "time-expires": "2022-11-21T23:00:00+00:00"
    }
  ]
}

oci os preauth-request get --namespace <object_storage_namespace> --bucket-name <bucket_name> --par-id <preauthenticated_request_id>

For example:

oci os preauth-request get --namespace MyNamespace --bucket-name MyParBucket --par-id YOExDlFsNYBNEwF8Uo4aK8WHiz59enVQm1aID+4cxFobgcaofVbZkg371rxK+6Vb
{
  "data": {
    "access-type": "AnyObjectReadWrite",
    "bucket-listing-action": "ListObjects",
    "id": "YOExDlFsNYBNEwF8Uo4aK8WHiz59enVQm1aID+4cxFobgcaofVbZkg371rxK+6Vb",
    "name": "PrefixedObjectsReadWritePAR",
    "object-name": "service",
    "time-created": "2021-04-01T15:35:40.609000+00:00",
    "time-expires": "2022-11-21T23:00:00+00:00"
  }
}