IBM Cloud API Docs

Introduction

Last updated: 2025-05-28

This is a new API for configuring IBM Cloud Object Storage buckets.

This API will evolve to cover the full suite of bucket configuration options provided today by extensions made to the modified S3 API. The COS Resource Configuration API now supports:

  • Viewing non-mutable bucket metadata (CRNs, timestamps, and usage info)
  • Viewing and setting IP address access filters.
  • Viewing and setting Activity Tracker events for object operations.

The Configuration API supports two request methods. The Get bucket configuration method reads a bucket's metadata, and returns an entity tag (ETag) header that identifies the current configuration. The tag is updated when some piece of mutable configuration metadata changes. Use the ETag with an if-match header in the Update bucket configuration method to ensure that you are overwriting the correct configuration.

PATCH operations can update multiple fields in the same request.

What is mutable configuration metadata? There's a lot of useful but non-mutable metadata associated with a bucket: its name, location, class, the service instance it belongs to, the number of objects it holds, and so on. None of those values can be directly edited by a user but are important for intelligent data management and are necessary for integration with other IBM Cloud services. In contrast, mutable bucket metadata adds functionality or alters behavior. In this initial version of the Configuration API, the only such metadata is a bucket's firewall, Activity Tracker, and Metrics Monitoring configurations.

In direct contrast to an S3 API, the Configuration API doesn't rely on separate methods to access different bucket parameters. For example, in an S3 API you might use these methods:

  1. Read the configuration of a bucket firewall by sending GET {endpoint}/{bucket}?firewall.
  2. Read the configuration location with GET {endpoint}/{bucket}?location.
  3. Check whether the configuration has Key Protect enabled by sending HEAD {endpoint}/{bucket} and reviewing the response headers.

Instead, the Configuration API uses a single JSON document to describe all aspects of a bucket's metadata and configuration with the Get the bucket configuration method. To update the configuration, the Configuration API uses JSON Merge Patch semantics to make updates directly to the bucket's metadata. Although you can only update a bucket's IP address access filter right now, the API might be updated to support making other updates. For example, you might be able to add a lifecycle rule, remove a firewall, and update a default retention period in a single request.

Some IDEs (such as PyCharm) may produce warnings about unused classes or methods. This is an artifact of the code generation tooling that allows for the passing of objects in named parameters, but generates a docstring that causes some linting tools to raise a warning.

JavaScript developers can use this SDK to interact with the Object Storage Resource Configuration API. For more information, see the COS Resource Configuration SDK for Java API Reference.

The SDK is supported on Java versions 1.6 and later.

JavaScript developers can use this SDK to interact with the Object Storage Resource Configuration API. For more information, see the COS Resource Configuration SDK for Java API Reference.

The SDK is supported on Node versions 8.x and later.

Python developers can use this SDK to interact with Object Storage Resource Configuration API. For more information, see the COS Resource Configuration SDK for Python API Reference.

Go developers can use this SDK to interact with Object Storage Resource Configuration API. For more information, see the COS Resource Configuration SDK for Go API Reference.

The SDK supports Go versions 1.12 and above.

The code examples on this tab use the Resource Configuration client library that is provided for Java.

Maven

<dependency>
  <groupId>com.ibm.cos.config</groupId>
  <artifactId>ibm-cos-java-config</artifactId>
</dependency>

GitHub

https://github.com/IBM/ibm-cos-sdk-java-config

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install ibm-cos-sdk-config

GitHub

https://github.com/IBM/ibm-cos-sdk-js-config

The code examples on this tab use the client library that is provided for Python.

Installation

pip install --upgrade ibm-cos-sdk-config

GitHub

https://github.com/IBM/ibm-cos-sdk-python-config

The code examples on this tab use the client library that is provided for Go.

go get -u github.com/IBM/ibm-cos-sdk-go-config

GitHub

https://github.com/IBM/ibm-cos-sdk-go-config

Endpoint URLs

Unlike the S3-compatible API for reading and writing data, the Configuration API uses a single, global service endpoint. Whether getting or updating metadata, for buckets located in the eu geo, us-south region, ams01 zone, or any other storage location, the request uses the same endpoint URL: https://config.cloud-object-storage.cloud.ibm.com/v1.

Note that the endpoint URL actually contains three parts: a protocol (https://), a host (config.cloud-object-storage.cloud.ibm.com), and a version (v1). The SDKs will construct this by default, but if sending requests using curl or any other REST API utility keep in mind that the endpoint requires both the protocol and version.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

Element Description
http_status_code HTTP status code for the response. Integer. Example: 200
code Error code. String. Example: AccessDenied
message Error message. String. Example: Access Denied
resource Target of the failed request. String. Example: Bucket123
ibm_cos_request_id Unique identifier for this request. String. Example: 5043294b-de39-4034-881a-92afbed1453d

Example error object:

{
  "http_status_code": 403,
  "code": "AccessDenied",
  "message": "Access Denied",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861"
}

Authentication

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token.

To retrieve an access token:

curl -X POST https://iam.cloud.ibm.com/identity/token \
  -H "content-type: application/x-www-form-urlencoded" \
  -H "accept: application/json" \
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

To retrieve an access token:

To be added

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

To create a client that will automatically handle token management:

const COS = require('ibm-cos-sdk-config/resource-configuration/v1')
const IAMAUTHENTICATOR = require('ibm-cos-sdk-config/auth');

clientInfo = new IamAuthenticator({
  apikey: 'apikey',
})

const client = new COS(clientInfo);

Replace apikey with an API key.

Now client is ready to make requests.

To create a client that will automatically handle token management:

from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator(
  apikey = 'apikey'
)

client = ResourceConfigurationV1(authenticator=api_key)

Replace api_key with a valid API key.

Now client is ready to make requests.

To retrieve an access token:

To be added

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

Additional headers

Request Parameter Description
authorization Required IBM Cloud IAM bearer token. String.
content-type The content type of the request body. String. Example: application/json.
Response Parameter Description
Date Timestamp of the response. String. Example: Sun, 13 Jan 2019 18:00:56 GMT
Content-Type All responses are of type application/json. Only returned if there is a response body (such as GET). String.
Content-Length Length in bytes of the response body. Integer. Only returned if there is a response body (such as GET). Example: 255
ETag Entity tag (per RFC 7232) of the current state of configuration. String. Example: "3ee236f6-0f8e-4171-8cec-050e4c87be48"
ibm-cos-config-api-ver The version of this API. String. Example: 1.0
ibm-cos-request-id Unique identifier for this request. String. Example: 5043294b-de39-4034-881a-92afbed1453d

Methods

Add a new backup policy to the COS Bucket

Attach a new Backup Policy on a bucket.

This request results in the creation of a single, new RecoveryRange on the destination BackupVault.

Deletion and re-creation of a BackupPolicy to the same BackupVault destination will generate a new RecoveryRange.

The following shall be validated. Any failure to validate shall cause a HTTP 400 to be returned.

  • the source-bucket must have cloud-object-storage.backup_vault.sync permissions on the Backup Vault
  • the source-bucket must have versioning-on
  • the Backup Vault must exist and be able to be contacted by the source-bucket
  • the source-bucket must not have an existing BackupPolicy targeting the Backup Vault
  • the source-bucket must not have a BackupPolicy with the same policy_name
  • the source-bucket must have fewer than 3 total BackupPolicies
POST /buckets/{bucket}/backup_policies

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for creation of a bucket backup policy.

  • cloud-object-storage.bucket.post_backup_policy

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket-backup-policy.create

Request

Custom Headers

  • MD5
    string

    MD5 hash of content. If provided, the hash of the request must match.

    Possible values: length = 36, Value must match regular expression ^[a-fA-F0-9]{32}$

Path Parameters

  • bucket
    Required*
    string

    Name of the COS Bucket name.

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

Request Body

Required*
BackupPolicyPrototype

A backup policy

Response

Response Body

BackupPolicy

The current backup coverage for a COS Bucket.

Status Code

  • 201

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "policy_name": "myBackupPolicy",
  "initial_retention": {
    "delete_after_days": 10
  },
  "backup_type": "continuous",
  "policy_id": "44d3dd41-d616-4d25-911a-9ef7fbf28aef",
  "policy_status": "pending",
  "target_backup_vault_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:1a0ec336-f391-4091-a6fb-5e084a4c56f4:backup-vault:backup-vault-name"
}

List BackupPolicies

Get all backup policies on a bucket.

This request generates the "cloud-object-storage.bucket-backup-policy.list" ActivityTracking event.

GET /buckets/{bucket}/backup_policies

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for listing of bucket backup policies.

  • cloud-object-storage.bucket.list_backup_policies

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket-backup-policy.list

Request

Path Parameters

  • bucket
    Required*
    string

    Name of the COS Bucket name.

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

Response

Response Body

BackupPolicyCollection

A collection of backup policies.

Status Code

  • 200

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • [
  {
    "policy_name": "myBackupPolicy",
    "initial_retention": {
      "delete_after_days": 10
    },
    "backup_type": "continuous",
    "policy_id": "44d3dd41-d616-4d25-911a-9ef7fbf28aef",
    "policy_status": "active",
    "target_backup_vault_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:backup-vault:backup-vault-name"
  }
]

Get BackupPolicy

Read a specific backup policy on a bucket.

GET /buckets/{bucket}/backup_policies/{policy_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for viewing a bucket backup policy.

  • cloud-object-storage.bucket.get_backup_policy

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket-backup-policy.read

Request

Path Parameters

  • bucket
    Required*
    string

    name of the bucket affected

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

  • policy_id
    Required*
    string

    uuid of the BackupPolicy

    Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response

Response Body

BackupPolicy

The current backup coverage for a COS Bucket.

Status Code

  • 200

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "policy_name": "myBackupPolicy",
  "backup_type": "continuous",
  "policy_id": "44d3dd41-d616-4d25-911a-9ef7fbf28aef",
  "policy_status": "active",
  "target_backup_vault_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:1a0ec336-f391-4091-a6fb-5e084a4c56f4:backup-vault:backup-vault-name",
  "initial_retention": {
    "delete_after_days": 10
  }
}

Delete a BackupPolicy

Delete a specific BackupPolicy.

DELETE /buckets/{bucket}/backup_policies/{policy_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for deleting a bucket backup policy.

  • cloud-object-storage.bucket.delete_backup_policy

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.bucket-backup-policy.delete

Request

Path Parameters

  • bucket
    Required*
    string

    name of the bucket affected

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

  • policy_id
    Required*
    string

    uuid of the BackupPolicy

    Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response

Status Code

  • 204

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

No Sample Response

This method does not specify any sample responses.

list BackupVaults

Returns a list of BackupVault CRNs owned by the account.

GET /backup_vaults

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for listing all the backup vaults in a service instance.

  • cloud-object-storage.backup_vault.list_account_backup_vaults

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-vault.list

Request

Query Parameters

  • service_instance_id
    Required*
    string

    Name of the service_instance to list BackupVaults for.

    Possible values: length = 32, Value must match regular expression ^[0-9a-f]{32}$

  • token
    string

    the continuation token for controlling pagination

    Possible values: 1 ≤ length ≤ 1600, Value must match regular expression ^[A-Za-z0-9-\_\=]{1,1600}$

Response

Response Body

BackupVaultCollection

A listing of backup vaults

Status Code

  • 200

    Successful operation

  • 400

    Bad Request, service_instance_id header param is missing, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "next": {
    "token": "SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz",
    "href": "config.cloud-object-storage.cloud.ibm.com/v1/backup_vaults?token=1znNRhmyheG-pm6mlMKFsoxcKXFnW1hgBb2_6ZReqHduL3rivfeBWHeyL-OaJvtfVZjKrgRVmODtOdVeQEXkKCxDWpA5hRWuv9WgTPR2eLIN9fbEaTxqdNO4dp0sQeHh4HO-13nTgRV_1QGiR1QFzREHX3wzquLn9o_1DZZAEP-vAY2V8d6BCA1z2krhpMfswKJ8r6UynUc0W5JHSH4auwJ6jC-h8sc8NEcQpHUx2Ep4oxebmtJMaycQSjLA3J2fdcYuysKq3YIcszDnPte0zwr25x5_GmBrxlgd2oesjfyTaLHfIg1g4TD0uH9m9aEAv"
  },
  "backup_vaults": [
    "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:otherbackupvault",
    "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:backupvault"
  ]
}

create a BackupVault

Creates a BackupVault.

Certain fields will be returned only if the user has specific permissions:

  • activity_tracking requires cloud-object-storage.backup_vault.put_activity_tracking
  • metrics_monitoring requires cloud-object-storage.backup_vault.put_metrics_monitoring
POST /backup_vaults

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

Allows for creating a backup vault in a service instance.

  • cloud-object-storage.backup_vault.post_backup_vault

  • cloud-object-storage.backup_vault.put_activity_tracking

  • cloud-object-storage.backup_vault.put_metrics_monitoring

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-vault.create

Request

Query Parameters

  • service_instance_id
    Required*
    string

    Name of the service_instance to list BackupVaults for.

    Possible values: length = 32, Value must match regular expression ^[0-9a-f]{32}$

Request Body

Required*
BackupVaultPrototype

A Backup Vault config object

Response

Response Body

BackupVault

Metadata associated with a backup vault.

Status Code

  • 201

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:mybackupvault",
  "service_instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436::",
  "time_created": "2024-06-02T12:00:00.000Z",
  "time_updated": "2024-06-02T12:00:00.000Z",
  "bytes_used": 0,
  "region": "us-south",
  "backup_vault_name": "mybackupvault"
}

get the config for a Backup Vault

Gets configuration information for a Backup Vault.

Certain fields will be returned only if the user has specific permissions:

  • activity_tracking requires cloud-object-storage.backup_vault.get_activity_tracking
  • metrics_monitoring requires cloud-object-storage.backup_vault.get_metrics_monitoring
  • sse_kp_customer_root_key_crn requires cloud-object-storage.backup_vault.get_crk_id
GET /backup_vaults/{backup_vault_name}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

Allows for reading backup vault configuration.

  • cloud-object-storage.backup_vault.get_basic

  • cloud-object-storage.backup_vault.get_activity_tracking

  • cloud-object-storage.backup_vault.get_metrics_monitoring

  • cloud-object-storage.backup_vault.get_crk_id

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-vault-configuration.read

Request

Path Parameters

  • backup_vault_name
    Required*
    string

    Name of the backup-vault to create or update.

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

Response

Response Body

BackupVault

Metadata associated with a backup vault.

Status Code

  • 200

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:mybackupvault",
  "service_instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436::",
  "time_created": "2024-06-02T12:00:00.000Z",
  "time_updated": "2024-06-02T12:00:00.000Z",
  "bytes_used": 0,
  "region": "us-south",
  "backup_vault_name": "mybackupvault"
}

Update the config on a Backup Vault

Update the Backup Vault config via JSON Merge Patch update semantics.

In particular, note that providing an empty object ({}) to either field in the request body will remove any existing configuration.

Requires that the user have specific permissions depending on what is being changed:

  • activity_tracking requires cloud-object-storage.backup_vault.put_activity_tracking
  • metrics_monitoring requires cloud-object-storage.backup_vault.put_metrics_monitoring
PATCH /backup_vaults/{backup_vault_name}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

Allows for updating specific backup vault configurations.

  • cloud-object-storage.backup_vault.put_activity_tracking

  • cloud-object-storage.backup_vault.put_metrics_monitoring

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-vault-configuration.update

Request

Custom Headers

  • If-Match
    string

    Conditionally update the Backup Vault config if and only if the ETag of the existing config exactly matches the provided If-Match MD5.

    Possible values: length = 36, Value must match regular expression ^[a-fA-F0-9]{32}$

Path Parameters

  • backup_vault_name
    Required*
    string

    Name of the backup-vault to create or update.

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

Request Body

Required*
application/merge-patch+jsonBackupVaultPatch

A Backup Vault config object containing changes to apply to the existing Backup Vault config.

Response

Response Body

BackupVault

Metadata associated with a backup vault.

Status Code

  • 200

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4-e6a7-40e3-8660-20847e525436:backup-vault:mybackupvault",
  "service_instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436::",
  "time_created": "2024-06-02T12:00:00.000Z",
  "time_updated": "2024-06-02T12:00:00.000Z",
  "bytes_used": 0,
  "region": "us-south",
  "backup_vault_name": "mybackupvault"
}

Delete an empty Backup Vault

Delete the Backup Vault.

Requires that the BackupVault not contain any RecoveryRanges.

DELETE /backup_vaults/{backup_vault_name}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for deleting a backup vault.

  • cloud-object-storage.backup_vault.delete_backup_vault

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-vault.delete

Request

Path Parameters

  • backup_vault_name
    Required*
    string

    Name of the backup-vault to create or update.

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

Response

Status Code

  • 204

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

No Sample Response

This method does not specify any sample responses.

List RecoveryRanges on a backup vault

List RecoveryRanges on a backup vault. Lists all available ranges for all source resources by default. The ?source_resource_crn query parameter will limit the list to only ranges for the specified resource.

GET /backup_vaults/{backup_vault_name}/recovery_ranges

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for listing the recovery ranges in a backup vault.

  • cloud-object-storage.backup_vault.list_recovery_ranges

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-recovery-range.list

Request

Path Parameters

  • backup_vault_name
    Required*
    string

    name of BackupVault

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

Query Parameters

  • source_resource_crn
    string

    CRN of source resource to filter on. This limits ranges returned to only ranges where the source_resource_crn matches the parameter value.

    Possible values: 107 ≤ length ≤ 140, Value must match regular expression ^crn:v1:bluemix:public:cloud-object-storage:global:[0-9a-f]{8}:[0-9a-f\-]{32,36}:bucket:[a-z0-9][a-z0-9\-\.]{3,63}$

  • latest
    string

    If "true", then return only the latest RecoveryRange for each source-resource that is backed up.

    If "false" or not specified, then the default behavior is produced.

    Value is can insensative. If any value is provided other than "true" or "false" then return 400.

    Possible values: 4 ≤ length ≤ 5, Value must match regular expression ^(T|t)(R|r)(U|u)(E|e)|(F|f)(A|a)(L|l)(S|s)(E|e)$

  • token
    string

    the continuation token for controlling pagination.

    Possible values: 1 ≤ length ≤ 1600, Value must match regular expression ^[A-Za-z0-9-\_\=]{1,1600}$

Response

Response Body

RecoveryRangeCollection

A collection of recovery ranges

Status Code

  • 200

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "next": {
    "token": "SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz",
    "href": "config.cloud-object-storage.cloud.ibm.com/v1/backup_vaults/mybackupvault/recovery_ranges?token=1znNRhmyheG-pm6mlMKFsoxcKXFnW1hgBb2_6ZReqHduL3rivfeBWHeyL-OaJvtfVZjKrgRVmODtOdVeQEXkKCxDWpA5hRWuv9WgTPR2eLIN9fbEaTxqdNO4dp0sQeHh4HO-13nTgRV_1QGiR1QFzREHX3wzquLn9o_1DZZAEP-vAY2V8d6BCA1z2krhpMfswKJ8r6UynUc0W5JHSH4auwJ6jC-h8sc8NEcQpHUx2Ep4oxebmtJMaycQSjLA3J2fdcYuysKq3YIcszDnPte0zwr25x5_GmBrxlgd2oesjfyTaLHfIg1g4TD0uH9m9aEAv"
  },
  "recovery_ranges": [
    {
      "recovery_range_id": "44d3dd41-d616-4d25-911a-9ef7fbf28aef",
      "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
      "backup_policy_name": "myBackupPolicy",
      "range_start_time": "2024-06-02T12:00:00.000Z",
      "range_end_time": "2024-06-03T12:00:00.000Z",
      "range_create_time": "2024-06-02T12:00:00.000Z",
      "retention": {
        "delete_after_days": 100
      }
    },
    {
      "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
      "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
      "backup_policy_name": "myBackupPolicy",
      "range_start_time": "2024-06-04T12:00:00.000Z",
      "range_end_time": "2024-06-05T12:00:00.000Z",
      "range_create_time": "2024-06-04T12:00:00.000Z",
      "retention": {
        "delete_after_days": 100
      }
    }
  ]
}

get RecoveryRange info

Get info for a specific RecoveryRange.

GET /backup_vaults/{backup_vault_name}/recovery_ranges/{recovery_range_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for viewing a recovery range a backup vault.

  • cloud-object-storage.backup_vault.get_recovery_range

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-recovery-range.read

Request

Path Parameters

  • backup_vault_name
    Required*
    string

    name of BackupVault to update

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

  • recovery_range_id
    Required*
    string

    ID of the RecoveryRange to update

    Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response

Response Body

RecoveryRange

Metadata associated with a recovery range.

Status Code

  • 200

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
  "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
  "backup_policy_name": "myBackupPolicy",
  "range_start_time": "2024-06-04T12:00:00.000Z",
  "range_end_time": "2024-06-05T12:00:00.000Z",
  "range_create_time": "2024-06-04T12:00:00.000Z",
  "retention": {
    "delete_after_days": 100
  }
}

patch RecoveryRange info

Update a RecoveryRange via JSON-merge-patch semantics.

This request only supports increasing the retention.delete_after_days value.

PATCH /backup_vaults/{backup_vault_name}/recovery_ranges/{recovery_range_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for updating a recovery range on a backup vault.

  • cloud-object-storage.backup_vault.put_retention

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-recovery-range.update

Request

Path Parameters

  • backup_vault_name
    Required*
    string

    name of BackupVault to update

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

  • recovery_range_id
    Required*
    string

    ID of the RecoveryRange to update

    Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Request Body

Required*
application/merge-patch+jsonRecoveryRangePatch

The RecoveryRange configuration elements that are to be changed.

Response

Response Body

RecoveryRange

Metadata associated with a recovery range.

Status Code

  • 200

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "retention": {
    "delete_after_days": 200
  }
}

Initiate a Restore

Initiates a restore operation against some RecoveryRange to some destination bucket.

The following shall be validated. Any failure to validate shall cause a HTTP 400 to be returned.

  • The specified RecoveryRange must exist
  • The restore time must be within the RecoveryRange
  • the target-bucket must exist and be able to be contacted by the Backup Vault
  • target-bucket must have versioning-on
  • the Backup Vault must have cloud-object-storage.bucket.restore_sync permissions on the target-bucket
POST /backup_vaults/{backup_vault_name}/restores

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for triggering a restore on a backup vault.

  • cloud-object-storage.backup-vault.post_restore

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-restore.create

Request

Path Parameters

  • backup_vault_name
    Required*
    string

    name of BackupVault to restore from

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

Request Body

Required*
RestorePrototype

A restore config

Examples: 
{
  "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
  "restore_point_in_time": "2024-06-04T12:12:00.000Z",
  "restore_type": "in_place",
  "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket"
}

Response

Response Body

Restore

Metadata associated with a requested restore operation.

Status Code

  • 201

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
  "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
  "restore_point_in_time": "2024-06-04T12:12:00.000Z",
  "restore_type": "in_place",
  "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket",
  "restore_id": "b0bcb32b-0fa9-423c-b10b-9d4328e5fc63",
  "restore_status": "initializing",
  "init_time": "2024-06-10T12:12:00.000Z"
}

List Restores

List all current and complete restores.

GET /backup_vaults/{backup_vault_name}/restores

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for listing restores on a backup vault.

  • cloud-object-storage.backup_vault.list_restores

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-restore.list

Request

Path Parameters

  • backup_vault_name
    Required*
    string

    name of BackupVault to restore from

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

Query Parameters

  • token
    string

    the continuation token for controlling pagination.

    Possible values: 1 ≤ length ≤ 1600, Value must match regular expression ^[A-Za-z0-9-\_\=]{1,1600}$

Response

Response Body

RestoreCollection

A list of restore operations.

Status Code

  • 200

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "next": {
    "token": "SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz",
    "href": "config.cloud-object-storage.cloud.ibm.com/v1/backup_vaults/mybackupvault/restores?Token=SWYwNTZMflFmZUgheGNcNHMuIm9OMTFz"
  },
  "restores": [
    {
      "restore_id": "b0bcb32b-0fa9-423c-b10b-9d4328e5fc63",
      "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
      "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
      "restore_point_in_time": "2024-06-04T12:12:00.000Z",
      "restore_type": "in_place",
      "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket",
      "restore_status": "running",
      "restore_percent_progress": 50,
      "init_time": "2024-06-10T12:12:00.000Z"
    },
    {
      "restore_id": "3deefef0-3ed7-492c-8828-00fb33e64f88",
      "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
      "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
      "restore_point_in_time": "2024-06-04T12:12:00.000Z",
      "restore_type": "in_place",
      "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:othertargetbucket",
      "restore_status": "initializing",
      "init_time": "2024-06-10T12:24:00.000Z"
    }
  ]
}

Get Restore

Introspect on a specific restore.

GET /backup_vaults/{backup_vault_name}/restores/{restore_id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

Allows for viewing a restore on a backup vault.

  • cloud-object-storage.backup_vault.get_restore

Auditing

Calling this method generates the following auditing event.

  • cloud-object-storage.backup-restore.read

Request

Path Parameters

  • backup_vault_name
    Required*
    string

    name of BackupVault that the restore occured on

    Possible values: 3 ≤ length ≤ 63, Value must match regular expression ^(?!^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$)(^[a-z0-9][a-z0-9\-\.]{1,61}[a-z0-9]$)$

  • restore_id
    Required*
    string

    id of the restore to introspect on

    Possible values: length = 36, Value must match regular expression ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response

Response Body

Restore

Metadata associated with a requested restore operation.

Status Code

  • 200

    Successful operation

  • 400

    Bad Request, or the Backup feature has not been enabled.

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal Service Error

  • 503

    Unavailable

Example responses
  • {
  "restore_id": "b0bcb32b-0fa9-423c-b10b-9d4328e5fc63",
  "recovery_range_id": "6ff0d31c-7583-4463-8ae5-208752f5769c",
  "source_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:sourcebucket",
  "restore_point_in_time": "2024-06-04T12:12:00.000Z",
  "restore_type": "in_place",
  "target_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a1229395:8dfbcba4e6a740e3866020847e525436:bucket:targetbucket",
  "restore_status": "running",
  "restore_percent_progress": 50,
  "init_time": "2024-06-10T12:12:00.000Z"
}

Returns metadata for the specified bucket

Returns metadata for the specified bucket.

GET /b/{bucket}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

Allows reading of bucket metadata.

  • cloud-object-storage.bucket.list_bucket_crn

  • cloud-object-storage.bucket.get_firewall

  • cloud-object-storage.bucket.get_activity_tracking

  • cloud-object-storage.bucket.get_metrics_monitoring

  • cloud-object-storage.bucket.get_protection_management

Request

Path Parameters

  • bucket
    Required*
    string

    Name of a bucket.

  • curl https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket   -H 'authorization: bearer $IAM_TOKEN'
  • import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

public class GetMetadata {

    private static final String BUCKET_NAME = <BUCKET_NAME>;
    private static final String API_KEY = <API_KEY>;
    public static void main(String[] args) {
        IamAuthenticator authenticator = new IamAuthenticator.Builder()
                .apiKey(API_KEY)
                .build();
        ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);
        GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();

        Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();
        ActivityTracking activityTrackingResponse = bucket.getActivityTracking();
        MetricsMonitoring metricsMonitoringResponse = bucket.getMetricsMonitoring();
        Firewall firewallResponse = bucket.getFirewall();
        ProtectionManagementResponse protectionManagementResponse = bucket.getProtectionManagement();
    }
}
  • from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

api_key = '<API_KEY>'
bucket_name = '<BUCKET_NAME>'

authenticator = IAMAuthenticator(
  apikey=api_key
)
rc_client = ResourceConfigurationV1(authenticator=authenticator)
config = rc_client.get_bucket_config(bucket_name)
print(config)
  • const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
const { IamAuthenticator } = require('ibm-cos-sdk-config/auth');

// Replace with your API key and bucket name
const apiKey = 'api-key';
const bucketName = 'bucket-name';

const authenticator = new IamAuthenticator({
  apikey: apiKey
});

const rcConfig = { authenticator: authenticator };
const client = new ResourceConfigurationV1(rcConfig);
function getBucketMetadata() {
    console.log('Getting bucket metadata...');
    const params = { bucket: bucketName };
    client.getBucketConfig(params)
        .then(response => {
            console.log('Bucket Metadata:', response.result);
        })
        .catch(err => {
            console.error('Error retrieving bucket metadata:', err);
      });
  }
getBucketMetadata()
  • import (
  fmt
  "github.com/IBM/go-sdk-core/core"
  rc "github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1"
)

const (
  apiKey = '<API_KEY>'
  bucketName = '<BUCKET_NAME>'
)

authenticator := &core.IamAuthenticator{
      ApiKey:  apiKey,
}
service, _ := rc.NewResourceConfigurationV1(&rc.ResourceConfigurationV1Options{
      Authenticator: authenticator,
})
getBucketConfigOptions := &rc.GetBucketConfigOptions{
  Bucket: core.StringPtr(bucketName),
}
result, response, _ := service.GetBucketConfig(getBucketConfigOptions)
fmt.Println(result)
fmt.Println(response)

Response

Response Body

Bucket

A bucket.

Status Code

  • 200

    Success

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not Found

  • 500

    Internal Server Error

Example responses
  • {
  "name": "my-new-bucket",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/ 3bf0d9003abfb5d29761c3e97696b71c:xxxxxxx-6c4f-4a62-a165-696756d63903:bucket:my-new-bucket",
  "service_instance_id": "xxxxxxx-6c4f-4a62-a165-696756d63903",
  "service_instance_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/3bf0d9003abfb5d29761c3e97696b71c:xxxxxxx-6c4f-4a62-a165-696756d63903::",
  "time_created": "2018-03-26T16:23:36.980Z",
  "time_updated": "2018-10-17T19:29:10.117Z",
  "object_count": 764265234,
  "bytes_used": 28198745752445144
}
  • {
  "http_status_code": 400,
  "code": "InvalidRequest",
  "message": "The request contains invalid elements.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861"
}
  • {
  "code": "Unauthorized",
  "message": "The token provided is not valid.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 401
}
  • {
  "code": "AccessDenied",
  "message": "Access Denied",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 403
}
  • {
  "code": "NoSuchBucket",
  "message": "The specified bucket does not exist.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 404
}
  • {
  "code": "InternalError",
  "message": "Internal server error.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 500
}

Make changes to a bucket's configuration

Updates a bucket using JSON Merge Patch. This request is used to add functionality (like an IP access filter) or to update existing parameters. Primitives are overwritten and replaced in their entirety. It is not possible to append a new (or to delete a specific) value to an array. Arrays can be cleared by updating the parameter with an empty array []. A PATCH operation only updates specified mutable fields. Please don't use PATCH trying to update the number of objects in a bucket, any timestamps, or other non-mutable fields.

PATCH /b/{bucket}

Request

Custom Headers

  • If-Match
    string

    An Etag previously returned in a header when fetching or updating a bucket's metadata. If this value does not match the active Etag, the request will fail.

Path Parameters

  • bucket
    Required*
    string

    Name of a bucket.

Request Body

application/merge-patch+jsonBucketPatch

An object containing new configuration metadata.

Examples: 
{
  "firewall": {
    "allowed_ip": [
      "10.142.175.0/22",
      "10.198.243.79"
    ]
  }
}
{
  "activity_tracking": {
    "read_object_events": false,
    "write_object_events": true,
    "management_events": true
  }
}
  • curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket   -H 'authorization: bearer $IAM_TOKEN'   -d '{"firewall": {"allowed_ip": ["10.142.175.0/22", "10.198.243.79"]}}'
  • curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket   -H 'authorization: bearer $IAM_TOKEN'   -d '{"activity_tracking": {           "read_data_events": true,           "write_data_events": true,           "management_events": true}'
  • curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket   -H 'authorization: bearer $IAM_TOKEN'   -d '{"metrics_monitoring": {           "usage_metrics_enabled": true}'
  • curl -X PATCH https://config.cloud-object-storage.cloud.ibm.com/v1/b/my-bucket   -H 'authorization: bearer $IAM_TOKEN'   -d '{"protection_management": {           "requested_state": "activate",           "protection_management_token": $PM_TOKEN}}'
  • import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

import java.util.Arrays;

public class FirewallExample {

    private static final String BUCKET_NAME = <BUCKET_NAME>;
    private static final String API_KEY = <API_KEY>;
    private static List<String> IP_ARRAY = new ArrayList<String>();
    IP_ARRAY.add("x.x.x.x");
    IP_ARRAY.add("y.y.y.y");

    public static void main(String[] args) {
        IamAuthenticator authenticator = new IamAuthenticator.Builder()
                .apiKey(API_KEY)
                .build();

        ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);
        Firewall firewallConfig = new Firewall.Builder().allowedIp(IP_ARRAY).build();
        BucketPatch bucketPatch = new BucketPatch.Builder().firewall(firewallConfig).build();
        UpdateBucketConfigOptions update = new UpdateBucketConfigOptions
                .Builder(BUCKET_NAME)
                .bucketPatch(bucketPatch.asPatch())
                .build();
        RC_CLIENT.updateBucketConfig(update).execute();
        GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
        Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();
        Firewall firewallResponse = bucket.getFirewall();
        for(String ip: firewallResponse.allowedIp()){
          System.out.println(ip)
        }
    }
}
  • import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

public class ActivityTrackerExample {

    private static final String BUCKET_NAME = <BUCKET_NAME>;
    private static final String API_KEY = <API_KEY>;

    public static void main(String[] args) {
        IamAuthenticator authenticator = new IamAuthenticator.Builder()
                .apiKey(API_KEY)
                .build();
        ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);
        ActivityTracking activityTrackingConfig = new ActivityTracking().Builder()
                .readDataEvents(true)
                .writeDataEvents(true)
                .managementEvents(true)
                .build();
        BucketPatch bucketPatch = new BucketPatch.Builder().activityTracking(activityTrackingConfig).build();
        UpdateBucketConfigOptions update = new UpdateBucketConfigOptions
                .Builder(BUCKET_NAME)
                .bucketPatch(bucketPatch.asPatch())
                .build();

        RC_CLIENT.updateBucketConfig(update).execute();
        GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
        Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();

        ActivityTracking activityTrackingResponse = bucket.getActivityTracking();
        System.out.println("Read Data Events : " + activityTrackingResponse.readDataEvents());
        System.out.println("Write Data Events : " + activityTrackingResponse.writeDataEvents());
        System.out.println("Management Events : " + activityTrackingResponse.managementEvents());
    }
}
  • import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

public class MetricsMonitoringExample {

    private static final String BUCKET_NAME = <BUCKET_NAME>;
    private static final String API_KEY = <API_KEY>;

    public static void main(String[] args) {
        IamAuthenticator authenticator = new IamAuthenticator.Builder()
                .apiKey(API_KEY)
                .build();
        ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);
        MetricsMonitoring metricsMonitoringConfig = new MetricsMonitoring().Builder()
              .requestMetricsEnabled(true)
              .usageMetricsEnabled(true)
              .build();
        BucketPatch bucketPatch = new BucketPatch.Builder().metricsMonitoring(metricsMonitoringConfig).build();
        UpdateBucketConfigOptions update = new UpdateBucketConfigOptions
                .Builder(BUCKET_NAME)
                .bucketPatch(bucketPatch.asPatch())
                .build();
        RC_CLIENT.updateBucketConfig(update).execute();

        GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
        Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();
        MetricsMonitoring metricsMonitoringResponse = bucket.getMetricsMonitoring();
        System.out.println("Usage Metrics Enabled  : " + metricsMonitoringResponse.usageMetricsEnabled());
        System.out.println("Request Metrics Enabled : " + metricsMonitoringResponse.requestMetricsEnabled());
    }
}
  • import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

public class ProtectionManagementExample {

    private static final String BUCKET_NAME = <BUCKET_NAME>;
    private static final String API_KEY = <API_KEY>;
    private static final String PM_TOKEN = <PM_TOKEN>;

    public static void main(String[] args) {
        IamAuthenticator authenticator = new IamAuthenticator.Builder()
                .apiKey(API_KEY)
                .build();
        ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);
        ProtectionManagement protectionManagementConfig = new ProtectionManagement.Builder()
              .requestedState("activate")
              .protectionManagementToken(PM_TOKEN)
              .build();
        BucketPatch bucketPatch = new BucketPatch.Builder().protectionManagement(protectionManagementConfig).build();
        UpdateBucketConfigOptions update = new UpdateBucketConfigOptions
                .Builder(BUCKET_NAME)
                .bucketPatch(bucketPatch.asPatch())
                .build();
        RC_CLIENT.updateBucketConfig(update).execute();

        GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
        Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();
        ProtectionManagementResponse protectionManagementResponse = bucket.getProtectionManagement();
        List<ProtectionManagementResponseTokenEntry> ProtectionManagementResponseTokenEntries = protectionManagementResponse.tokenEntries();
        System.out.println("Token Applied Counter: " + protectionManagementResponse.tokenAppliedCounter());
        for(ProtectionManagementResponseTokenEntry tokenEntry: ProtectionManagementResponseTokenEntries) {
          System.out.println("Token Reference Id: " + tokenEntry.getTokenReferenceId());
        }
    }
}
  • from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

api_key = "<API_KEY>"
bucket_name = "<BUCKET_NAME>"
ip_array = ["x.x.x.x", "y.y.y.y"]

authenticator = IAMAuthenticator(apikey=api_key)
client = ResourceConfigurationV1(authenticator=authenticator)
firewall_config = {'firewall': {"allowed_ip": ip_array}}
client.update_bucket_config(bucket_name, bucket_patch=firewall_config)
  • from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

api_key = "<API_KEY>"
bucket_name = "<BUCKET_NAME>"

authenticator = IAMAuthenticator(apikey=api_key)
client = ResourceConfigurationV1(authenticator=authenticator)
activity_tracking_config = {'activity_tracking':{'read_data_events':True, 'write_data_events':True, 'management_events':True}}
client.update_bucket_config(bucket_name, bucket_patch=activity_tracking_config)
  • from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

api_key = "<API_KEY>"
bucket_name = "<BUCKET_NAME>"

authenticator = IAMAuthenticator(apikey=api_key)
client = ResourceConfigurationV1(authenticator=authenticator)
metrics_monitoring_config = {'metrics_monitoring': {'request_metrics_enabled':True, 'usage_metrics_enabled':True}}
client.update_bucket_config(bucket_name, bucket_patch=metrics_monitoring_config)
  • from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

api_key = "<API_KEY>"
bucket_name = "<BUCKET_NAME>"
pm_token = "<PM_TOKEN>"

authenticator = IAMAuthenticator(apikey=api_key)
client = ResourceConfigurationV1(authenticator=authenticator)
protection_management_config = {'protection_management': {'requested_state': 'activate', 'protection_management_token': pm_token}}
client.update_bucket_config(bucket_name, bucket_patch=protection_management_config)
  • const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
IamAuthenticator      = require('ibm-cos-sdk-config/auth');

var apiKey = "<API_KEY>"
var bucketName = "<BUCKET_NAME>"
var allowedIP = ["56.131.110.60"]

authenticator = new IamAuthenticator({apikey: apiKey})
rcConfig = {authenticator: authenticator}
const client = new ResourceConfigurationV1(rcConfig);

function addFirewall() {
    console.log('Updating bucket metadata...');

    var params = {
        bucket: bucketName,
        firewall: {
            allowed_ip: allowedIP
        }
    };

    client.updateBucketConfig(params, function (err, response) {
        if (err) {
            console.log("ERROR: " + err);
        } else {
            console.log(response.result);
        }
    });
}

addFirewall()
  • const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
IamAuthenticator      = require('ibm-cos-sdk-config/auth');

var apiKey = "<API_KEY>"
var bucketName = "<BUCKET_NAME>"

authenticator = new IamAuthenticator({apikey: apiKey})
rcConfig = {authenticator: authenticator}
const client = new ResourceConfigurationV1(rcConfig);

function addAT() {
    console.log('Updating bucket metadata...');

    var params = {
        bucket: bucketName,
        activityTracking: {
          "read_data_events": true,
          "write_data_events": true,
          "management_events": true
          }
    };

    client.updateBucketConfig(params, function (err, response) {
        if (err) {
            console.log("ERROR: " + err);
        } else {
            console.log(response.result);
        }
    });
}

addAT()
  • const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
IamAuthenticator      = require('ibm-cos-sdk-config/auth');

var apiKey = "<API_KEY>"
var bucketName = "<BUCKET_NAME>"

authenticator = new IamAuthenticator({apikey: apiKey})
rcConfig = {authenticator: authenticator}
const client = new ResourceConfigurationV1(rcConfig);

function addMM() {
    console.log('Updating bucket metadata...');

    var params = {
        bucket: bucketName,
        metricsMonitoring: {
          "request_metrics_enabled": true,
          "usage_metrics_enabled": true
          }
    };

    client.updateBucketConfig(params, function (err, response) {
        if (err) {
            console.log("ERROR: " + err);
        } else {
            console.log(response.result);
        }
    });
}

addMM()
  • const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
const { IamAuthenticator }    = require('ibm-cos-sdk-config/auth');

var apiKey     = "<API_KEY>"
var bucketName = "<BUCKET_NAME>"
var pmToken    = "<PM_TOKEN>"

const authenticator = new IamAuthenticator({apikey: apiKey})
const rcConfig = {authenticator: authenticator}
const client = new ResourceConfigurationV1(rcConfig);

function addPM() {
    var params = {
        bucket: bucketName,
        protectionManagement: {
          "requested_state": "activate",
          "protection_management_token": pmToken
          }
    };

    client.updateBucketConfig(params, function (err, data) {
        if (err) {
            console.log("ERROR: " + err);
        } else {
            console.log(data);
        }
    });
}

addPM()
  • import (
"github.com/IBM/go-sdk-core/core"
rc "github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1"
)

apiKey := "<ApiKey>"
bucketName := "<BucketName>"

authenticator := new(core.IamAuthenticator)
authenticator.ApiKey = apiKey
optionsRC := new(rc.ResourceConfigurationV1Options)
optionsRC.Authenticator = authenticator
rcClient, _ := rc.NewResourceConfigurationV1(optionsRC)

patchNameMap := make(map[string]interface{})
patchNameMap["firewall"] = &rc.Firewall{
  AllowedIp:     []string{"192.168.1.100"}
}
updateBucketConfigOptions := &rc.UpdateBucketConfigOptions{
  Bucket:      core.StringPtr(bucketName),
  BucketPatch: patchNameMap,
}
rcClient.UpdateBucketConfig(updateBucketConfigOptions)
  • import (
"github.com/IBM/go-sdk-core/core"
rc "github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1"
)

apiKey := "<ApiKey>"
bucketName := "<BucketName>"

authenticator := new(core.IamAuthenticator)
authenticator.ApiKey = apiKey
optionsRC := new(rc.ResourceConfigurationV1Options)
optionsRC.Authenticator = authenticator
rcClient, _ := rc.NewResourceConfigurationV1(optionsRC)

patchNameMap := make(map[string]interface{})
patchNameMap["activity_tracking"] = &rc.ActivityTracking{
  ReadDataEvents:     core.BoolPtr(true),
  WriteDataEvents:    core.BoolPtr(true),
  ManagementEvents:    core.BoolPtr(true)
}
updateBucketConfigOptions := &rc.UpdateBucketConfigOptions{
  Bucket:      core.StringPtr(bucketName),
  BucketPatch: patchNameMap,
}
rcClient.UpdateBucketConfig(updateBucketConfigOptions)
  • import (
"github.com/IBM/go-sdk-core/core"
rc "github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1"
)

apiKey := "<ApiKey>"
bucketName := "<BucketName>"

authenticator := new(core.IamAuthenticator)
authenticator.ApiKey = apiKey
optionsRC := new(rc.ResourceConfigurationV1Options)
optionsRC.Authenticator = authenticator
rcClient, _ := rc.NewResourceConfigurationV1(optionsRC)

patchNameMap := make(map[string]interface{})
patchNameMap["metrics_monitoring"] = &rc.MetricsMonitoring{
  RequestMetricsEnabled:     core.BoolPtr(true),
  UsageMetricsEnabled:    core.BoolPtr(true)
}
updateBucketConfigOptions := &rc.UpdateBucketConfigOptions{
  Bucket:      core.StringPtr(bucketName),
  BucketPatch: patchNameMap,
}
rcClient.UpdateBucketConfig(updateBucketConfigOptions)
  • import (
"github.com/IBM/go-sdk-core/core"
rc "github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1"
)

apiKey := "<ApiKey>"
bucketName := "<BucketName>"
pmToken := "<PMToken>"

authenticator := new(core.IamAuthenticator)
authenticator.ApiKey = apiKey
optionsRC := new(rc.ResourceConfigurationV1Options)
optionsRC.Authenticator = authenticator
rcClient, _ := rc.NewResourceConfigurationV1(optionsRC)

patchNameMap := make(map[string]interface{})
patchNameMap["protection_management"] = &rc.ProtectionManagement{
  RequestedState:     core.StringPtr("activate"),
  ProtectionManagementToken:    core.StringPtr(pmToken),
}
updateBucketConfigOptions := &rc.UpdateBucketConfigOptions{
  Bucket:      core.StringPtr(bucketName),
  BucketPatch: patchNameMap,
}
rcClient.UpdateBucketConfig(updateBucketConfigOptions)

Response

Status Code

  • 200

    Success

  • 400

    Bad Request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

    Not Found

  • 412

    Precondition Failed

  • 500

    Internal Server Error

Example responses
  • {
  "code": "InvalidRequest",
  "message": "The request contains invalid elements.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 400
}
  • {
  "code": "Unauthorized",
  "message": "The token provided is not valid.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 401
}
  • {
  "code": "AccessDenied",
  "message": "Access Denied",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 403
}
  • {
  "code": "NoSuchBucket",
  "message": "The specified bucket does not exist.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861",
  "http_status_code": 404
}
  • {
  "http_status_code": 412,
  "code": "PreconditionFailed",
  "message": "At least one of the preconditions specified were not met.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861"
}
  • {
  "http_status_code": 500,
  "code": "InternalError",
  "message": "Internal server error.",
  "resource": "my-new-bucket",
  "ibm_cos_request_id": "9f39ff2e-55d1-461b-a6f1-2d0b75138861"
}
id=curlclassName=tab-item-selected
Privacy statement
Terms of Use
Accessibility
Glossary
Submitting feedback