Branch: master
Clone or download
Bryan Keller
Latest commit 3d64741 Feb 5, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Release 1.4.2 Jan 30, 2019
apis Release 1.4.1 Dec 13, 2018
clients Release 1.4.1 Dec 13, 2018
lib Update version to 1.4.4-0 Feb 5, 2019
scripts Release 1.1.3 Feb 26, 2018
tasks Release 1.0.2 Oct 13, 2017
ts Release 1.4.2 Jan 30, 2019
.jshintrc Remove JSHint options CC doesn't understand Oct 2, 2014
.npmignore Release 1.4.2 Jan 30, 2019
.tesselinclude Adds .tesselinclude for resource deployment inclusion. Fixes gh-967 Apr 18, 2016
.travis.yml Run browser tests via Karma instead of custom phantomjs runner (#1352) Mar 8, 2017
.yardopts Release 1.0.2 Oct 13, 2017
.yardopts_guide Release 1.4.3 Feb 5, 2019
Gemfile Update navigation bar in template Jul 8, 2015
Gemfile.lock Update navigation bar in template Jul 8, 2015
LICENSE.txt Update copyright years throughout Jan 31, 2017 Release 1.4.2 Jan 30, 2019
Rakefile Don't need bundle/setup in Rakefile Mar 14, 2014
config.js.sample Initial IBM COS SDK Release Sep 12, 2017
configuration.sample Initial IBM COS SDK Release Sep 12, 2017
global.d.ts Bundles TypeScript definition files and adds generation of d.ts files… Nov 10, 2016
global.js Updates node and browser loaders Sep 8, 2016
index.d.ts Bundles TypeScript definition files and adds generation of d.ts files… Nov 10, 2016
index.js Add index.js for convenience Jul 8, 2014
package.json Update version to 1.4.4-0 Feb 5, 2019

IBM Cloud Object Storage - Node.js SDK

This package allows Node.js developers to write software that interacts with IBM Cloud Object Storage. It is a fork of the AWS SDK for Javascript library.


For release notes, see the CHANGELOG.

Quick start

You'll need:

  • An instance of COS.
  • An API key from IBM Cloud Identity and Access Management with at least Writer permissions.
  • The ID of the instance of COS that you are working with.
  • Token acquisition endpoint
  • Service endpoint
  • Node 4.0++.

These values can be found in the IBM Cloud Console by generating a 'service credential'.

Getting the SDK

The preferred way to install the IBM COS SDK for Node.js is to use the npm package manager for Node.js. Simply type the following into a terminal window:

npm install ibm-cos-sdk

Using a Service Credential

You can source credentials directly from a Service Credential JSON document generated in the IBM Cloud console saved to ~/.bluemix/cos_credentials. The SDK will automatically load these providing you have not explicitly set other credentials during client creation. If the Service Credential contain HMAC keys the client will use those and authenticate using a signature, otherwise the client will use the provided API key to authenticate using bearer tokens.

Example code

var AWS = require('ibm-cos-sdk');
var util = require('util');

var config = {
    endpoint: '<endpoint>',
    apiKeyId: '<api-key>',
    ibmAuthEndpoint: '',
    serviceInstanceId: '<resource-instance-id>',

var cos = new AWS.S3(config);

function doCreateBucket() {
    console.log('Creating bucket');
    return cos.createBucket({
        Bucket: 'my-bucket',
        CreateBucketConfiguration: {
          LocationConstraint: 'us-standard'

function doCreateObject() {
    console.log('Creating object');
    return cos.putObject({
        Bucket: 'my-bucket',
        Key: 'foo',
        Body: 'bar'

function doDeleteObject() {
    console.log('Deleting object');
    return cos.deleteObject({
        Bucket: 'my-bucket',
        Key: 'foo'

function doDeleteBucket() {
    console.log('Deleting bucket');
    return cos.deleteBucket({
        Bucket: 'my-bucket'

    .then(function() {
    .catch(function(err) {
        console.error('An error occurred:');

Immutable Object Storage

Users can configure buckets with an Immutable Object Storage policy to prevent objects from being modified or deleted for a defined period of time. The retention period can be specified on a per-object basis, or objects can inherit a default retention period set on the bucket. It is also possible to set open-ended and permanent retention periods. Immutable Object Storage meets the rules set forth by the SEC governing record retention, and IBM Cloud administrators are unable to bypass these restrictions. For more detail see the documentation.

Archive Tier Support

You can automatically archive objects after a specified length of time or after a specified date. Once archived, a temporary copy of an object can be restored for access as needed. Restore time may take up to 15 hours.

An archive policy is set at the bucket level by calling the putBucketLifecycle method on a client instance. A newly added or modified archive policy applies to new objects uploaded and does not affect existing objects. For more detail, see the documentation.

Getting Help

Feel free to use GitHub issues for tracking bugs and feature requests, but for help please use one of the following resources:


This SDK is distributed under the Apache License, Version 2.0, see LICENSE.txt and NOTICE.txt for more information.