Authenticating Access When Using the REST API

To request an authentication token, send a GET request to the authentication URL for your account. You’ll need your sign-in credentials to access your account and obtain the authentication URL to perform any operation on the resources.

Obtaining the Authentication URL

  1. Sign in to your Oracle Cloud account.

    See Signing In to Your Cloud Account in Getting Started with Oracle Cloud.

    The Infrastructure Classic Console is displayed.

  2. Look for Storage Classic.
  3. Select View Details from the Actions menu. Alternatively, click the Storage Classic link on the Dashboard page.

    On the resulting page, the details of your Oracle Cloud Infrastructure Object Storage Classic account are displayed.

  4. Note the authentication URL, which is displayed in the Auth V1 Endpoint field under the Additional Information section.

    For example: https://acme.storage.oraclecloud.com/auth/v1.0

    If the Auth V1 Endpoint field is not displayed, then you must construct the authentication URL.
    1. Note the REST Endpoint URL, which is displayed in the REST Endpoint field under the Additional Information section.

      For example: https://acme.storage.oraclecloud.com/v1/Storage-acme

    2. Delete the following portion of the REST Endpoint URL:

      v1/Storage-acme

      The edited URL is: https://acme.storage.oraclecloud.com/

    3. Append the following to the edited URL:

      auth/v1.0

      The equivalent authentication URL would be https://acme.storage.oraclecloud.com/auth/v1.0.

Using Your Account Details

You’ll need your sign-in credentials to access your account and perform any operation on the resources.

When you sign up for the account, you’ll receive a Welcome mail with your sign-in credentials.

Make a note of your sign-in credentials, as shown in the following example:
Description of new_account_information_email-2017.jpg follows
Description of the illustration new_account_information_email-2017.jpg

If you don't have your Welcome email, ask your account administrator for your Oracle Cloud user name, password, and identity domain.

Note:

For traditional accounts, you can request Oracle Cloud to send the email to the administrator again. See Resending Welcome Email with Administrator Sign-in Credentials.

If your user credentials are not authenticated, the service returns an HTTP response with a status code of 401 and no authentication token is returned.

If the credentials are authenticated, the service either returns the currently active authentication token or generates a new authenticate token. Authentication tokens are returned as the value of the HTTP header X-Auth-Token in the HTTP response. Requesting an authentication token with credentials that already have an active authentication token will not extend the expiration time of the existing authentication token.

Requesting an Authentication Token

When you send the GET request to the authentication URL, include the user credentials in the following headers:

  • Depending on the REST Endpoint URL in your account:
    • If you use the REST Endpoint URL, then include the header X-Storage-User: Storage-account_name:userName
    • If you use the REST Endpoint URL (Permanent), then include the header X-Storage-User: Storage-GUID:userName

      Note:

      The REST Endpoint (Permanent) URL is displayed for the accounts created after November 2017.
  • X-Storage-Pass: password
  • http://account_name.storage.oraclecloud.com/auth/v1.0 is the authentication URL.

Note:

For traditional accounts, the identity domain name and the account name are the same.

cURL Command Examples

Sample Cloud account with the following details:
  • Account name: acme

    For traditional accounts, account name and identity domain name are the same.

  • REST Endpoint URL: https://acme.storage.oraclecloud.com/v1/Storage-acme
  • REST Endpoint (Permanent) URL: https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365
  • Authentication URL: https://acme.storage.oraclecloud.com/auth/v1.0

cURL Command Examples – Requesting an Authentication Token:

  • Using the account name acme obtained from the REST Endpoint URL in the header X-Storage-User:
    curl -v -X GET \
         -H "X-Storage-User: Storage-acme:myUsername" \
         -H "X-Storage-Pass: myPassword" \
         https://acme.storage.oraclecloud.com/auth/v1.0
    

    The following is an example of the output of this command:

    > GET /auth/v1.0 HTTP/1.1
    > Host: acme.storage.oraclecloud.com
    > Accept: */*
    > X-Storage-User: Storage-acme:myUsername
    > X-Storage-Pass: myPassword
    
    < HTTP/1.1 200 OK
    < X-Storage-Url: https://acme.storage.oraclecloud.com/v1/Storage-acme
    < X-Storage-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
    < X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
    < X-Trans-Id: txba4aa8f776164c33b7aa587554c29fb6
    < Content-Length: 0
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Type: text/plain
    < Content-Language: en
    
  • Using the GUID 7b16fede61e1417ab83eb52e06f0e365 obtained from the REST Endpoint (Permanent) URL in the header X-Storage-User:
    curl -v -X GET \
         -H "X-Storage-User: Storage-7b16fede61e1417ab83eb52e06f0e365:myUsername" \
         -H "X-Storage-Pass: myPassword" \
         https://acme.storage.oraclecloud.com/auth/v1.0
    

    The following is an example of the output of this command:

    > GET /auth/v1.0 HTTP/1.1
    > Host: acme.storage.oraclecloud.com
    > Accept: */*
    > X-Storage-User: Storage-7b16fede61e1417ab83eb52e06f0e365:myUsername
    > X-Storage-Pass: myPassword
    
    < HTTP/1.1 200 OK
    < X-Storage-Url: https://acme.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365
    < X-Storage-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
    < X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
    < X-Trans-Id: txba4aa8f776164c33b7aa587554c29fb6
    < Content-Length: 0
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Type: text/plain
    < Content-Language: en
    

To use your authentication token, include it as the value of the X-Auth-Token HTTP header in every HTTP request to the service instance. If your authentication token is not valid, or has expired, the service returns an HTTP response with the status code 401 and the requested operation will fail. If the authentication token has expired, you must request a new token. If you are reading publicly accessible objects, you do not need to provide an authentication token in your HTTP request; anonymously accessible objects do not need an authentication token.

cURL Command Examples – Storing an Object in an Account Using an Authentication Token:

  • Using the REST Endpoint URL obtained from the REST Endpoint field:
    curl -v -X PUT \
         -H "X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6" \
         -d "Hello, World!" \
         https://acme.storage.oraclecloud.com/v1/Storage-acme/myContainer/myObject
    

    The following is an example of the output of this command:

    > PUT /v1/Storage-acme/myContainer/myObject HTTP/1.1
    > Host: acme.storage.oraclecloud.com
    > Accept: */*
    > X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
    > Content-Length: 13
    > Content-Type: application/x-www-form-urlencoded
    
    < HTTP/1.1 201 Created
    < Content-Length: 0
    < Etag: 65a8e27d8879283831b664bd8b7f0ad4
    < Content-Type: text/html; charset=UTF-8
    < X-Trans-Id: tx287a1a8e33cc45e5a1431817e3e87621
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Language: en
  • Using the Service Permanent REST Endpoint URL obtained from the REST Endpoint (Permanent) field:

    This cURL command example applies to the accounts created after November 2017.

    curl -v -X PUT \
         -H "X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6" \
         -d "Hello, World!" \
         https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer/myObject
    

    The following is an example of the output of this command:

    > PUT /v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer/myObject HTTP/1.1
    > Host: storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com
    > Accept: */*
    > X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
    > Content-Length: 13
    > Content-Type: application/x-www-form-urlencoded
    
    < HTTP/1.1 201 Created
    < Content-Length: 0
    < Etag: 65a8e27d8879283831b664bd8b7f0ad4
    < Content-Type: text/html; charset=UTF-8
    < X-Trans-Id: tx287a1a8e33cc45e5a1431817e3e87621
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Language: en