All Products
Search

This Product

    Object Storage Service:Manage bucket access permissions (Node.js SDK)

    Document Center

    Object Storage Service:Manage bucket access permissions (Node.js SDK)

    Last Updated:Mar 20, 2026

    Use the Node.js SDK to set and retrieve the access control list (ACL) of a bucket. Set the ACL at bucket creation time, or update it later.

    Prerequisites

    Before you begin, make sure that you have:

    • An Alibaba Cloud account

    • The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables set

    • The ali-oss npm package installed (npm install ali-oss)

    ACL types

    OSS supports three bucket-level ACL values:

    ACL valueWho can readWho can write
    privateBucket owner and authorized users onlyBucket owner and authorized users only
    public-readAnyoneBucket owner and authorized users only
    public-read-writeAnyoneAnyone
    Warning

    public-read and public-read-write expose your bucket to anonymous access. Use these ACL values only when you intend to serve public content.

    Set the ACL when creating a bucket

    Pass an acl option to putBucket to set the ACL at creation time.

    const OSS = require('ali-oss');

const client = new OSS({
  // Set yourregion to the region where the bucket is located.
  // Example: oss-cn-hangzhou for the China (Hangzhou) region.
  region: 'yourregion',
  // Load credentials from environment variables.
  // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

async function putBucket() {
  const acl = 'public-read';
  try {
    await client.putBucket('yourbucketname', { acl });
    console.log('Bucket created with ACL:', acl);
  } catch (error) {
    console.log(error);
  }
}

putBucket();

    Update the ACL of an existing bucket

    Call putBucketACL to change the ACL of a bucket after it is created.

    const OSS = require('ali-oss');

const client = new OSS({
  // Set yourregion to the region where the bucket is located.
  // Example: oss-cn-hangzhou for the China (Hangzhou) region.
  region: 'yourregion',
  // Load credentials from environment variables.
  // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

async function putBucketACL() {
  const acl = 'private';
  try {
    await client.putBucketACL('yourbucketname', acl);
    console.log('Bucket ACL updated to:', acl);
  } catch (error) {
    console.log(error);
  }
}

putBucketACL();

    Get the ACL of a bucket

    Call getBucketACL to retrieve the current ACL of a bucket. The ACL value is returned as result.acl.

    const OSS = require('ali-oss');

const client = new OSS({
  // Set yourregion to the region where the bucket is located.
  // Example: oss-cn-hangzhou for the China (Hangzhou) region.
  region: 'yourregion',
  // Load credentials from environment variables.
  // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this code.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'yourbucketname'
});

async function getBucketAcl() {
  try {
    const result = await client.getBucketACL('yourbucketname');
    console.log('Current ACL:', result.acl);
  } catch (error) {
    console.log(error);
  }
}

getBucketAcl();

    What's next