Class Access

Access control functions class for managing permissions on drives and drive items

This class provides methods for granting and revoking access to drives and drive items using role-based access control (RBAC). It handles both user and entity-based access control, supporting Users, OrgUsers, Agents, and Clients as accessors.

The class supports role-based permissions with different roles for different resource types:

  • Drive roles: READ_ONLY, VIEWER, CONTRIBUTOR, EDITOR, MANAGER
  • Directory roles: READ_ONLY, VIEWER, EDITOR, CONTRIBUTOR (includes create), MANAGER
  • File roles: READ_ONLY, VIEWER, EDITOR (no create), MANAGER

Note: CONTRIBUTOR role is only valid for directories (folders), not files, as files don't support the create action. Use DriveDirectoryRole for directories and DriveFileRole for files.

The class also supports various grant modes including cascade, path-based, and recursive access.

The class is typically accessed through the Drive or DriveItem classes rather than instantiated directly.

Example

Access through Drive class (role-based):

const drive = await client.drives.get({}, driveId);

// Grant editor role to an org user
await drive.access.grantByRole({ org_user: 'orguser123' }, 'EDITOR');

// Grant manager role with cascade to items
await drive.access.grantByRole(
  { org_user: 'orguser123' },
  'MANAGER',
  { cascade_to_items: true }
);

// Revoke all access
const result = await drive.access.revoke({ org_user: 'orguser123' });
console.log(`Revoked ${result.revoked_count} permissions`);

// List all accessors
const accessors = await drive.access.list();
console.log(`Drive has ${accessors.accessors.length} accessors`);

Example

Access through DriveItem class (directory):

const directory = await drive.items.get({}, directoryId);

// Grant editor role to an org user (directories support all roles)
await directory.access.grantByRole({ org_user: orgUserObj }, 'EDITOR');

// Grant CONTRIBUTOR role (valid for directories, includes create)
await directory.access.grantByRole({ org_user: 'orguser123' }, 'CONTRIBUTOR');

// Grant path-based access
await directory.access.grantByRole(
  { org_user: 'orguser123' },
  'EDITOR',
  { mode: 'path', folder_role: 'READ_ONLY' }
);

// Revoke all access
const result = await directory.access.revoke({ org_user: 'orguser123' });
console.log(`Removed ${result.revoked_count} permissions`);

Example

Access through DriveItem class (file):

const file = await drive.items.get({}, fileId);

// Grant editor role to an org user (files don't support CONTRIBUTOR)
await file.access.grantByRole({ org_user: orgUserObj }, 'EDITOR');

// Files cannot have CONTRIBUTOR role (no create action for files)
// await file.access.grantByRole({ org_user: 'orguser123' }, 'CONTRIBUTOR'); // ❌ Invalid

// Revoke all access
const result = await file.access.revoke({ org_user: 'orguser123' });
console.log(`Removed ${result.revoked_count} permissions`);

Constructors

constructor

Methods

grantByRole grant revoke list

Constructors

constructor

  • new Access(uri?: string): Access

    Creates a new Access instance

    Parameters

    • uri: string = ""

      Base URI for the access endpoint (typically set by Drive or DriveItem)

    Returns Access

    Example

    // Usually accessed through Drive or DriveItem classes
    const drive = await client.drives.get({}, driveId);
    const access = drive.access; // This calls the constructor internally

    // Direct instantiation (less common)
    const access = new Access('/drive/123');

Methods

grantByRole

  • grantByRole(
        accessor: Accessor,
        role: "READ_ONLY" | "VIEWER" | "CONTRIBUTOR" | "EDITOR" | "MANAGER",
        options?: GrantAccessOptions,
    ): Promise<GrantAccessResponse>

    Grant access to a drive or drive item using role-based permissions

    Creates permissions that allow the specified accessor to perform actions defined by the role on the resource.

    Parameters

    • accessor: Accessor

      Object specifying which entity to grant access to

      • Optionaluser?: string | User
      • Optionalorg_user?: string | OrgUser
      • Optionalagent?: string | Agent
      • Optionalclient?: string | Client
    • role: "READ_ONLY" | "VIEWER" | "CONTRIBUTOR" | "EDITOR" | "MANAGER"

      The role to grant:

      • For drives: READ_ONLY, VIEWER, CONTRIBUTOR, EDITOR, MANAGER
      • For directories: READ_ONLY, VIEWER, EDITOR, CONTRIBUTOR (with create), MANAGER
      • For files: READ_ONLY, VIEWER, EDITOR (no create), MANAGER
    • Optionaloptions: GrantAccessOptions

      Optional grant options for cascade, path, or recursive modes

    Returns Promise<GrantAccessResponse>

    Promise resolving to the granted permission details

    Throws

    If the API request fails

    Example

    Grant editor role to an org user:

    const drive = await client.drives.get({}, driveId);

    await drive.access.grantByRole(
      { org_user: 'orguser123' },
      'EDITOR'
    );

    Example

    Grant manager role with cascade to items:

    const drive = await client.drives.get({}, driveId);

    await drive.access.grantByRole(
      { org_user: 'orguser123' },
      'MANAGER',
      { cascade_to_items: true }
    );

    Example

    Grant path-based access to a directory:

    const item = await drive.items.get({}, itemId);

    await item.access.grantByRole(
      { org_user: 'orguser123' },
      'EDITOR',
      { mode: 'path', folder_role: 'READ_ONLY' }
    );

    Example

    Grant access to a file (cannot use CONTRIBUTOR):

    const file = await drive.items.get({}, fileId);

    // Files can only have VIEWER, EDITOR, or MANAGER
    await file.access.grantByRole(
      { org_user: 'orguser123' },
      'EDITOR' // CONTRIBUTOR is not valid for files
    );

    Example

    Grant access to a directory (can use CONTRIBUTOR):

    const directory = await drive.items.get({}, directoryId);

    // Directories can have CONTRIBUTOR which includes create permission
    await directory.access.grantByRole(
      { org_user: 'orguser123' },
      'CONTRIBUTOR' // Valid for directories
    );

grant

  • grant(
        accessor: Accessor,
        action: AccessAction,
    ): Promise<LegacyGrantAccessResponse>

    Grant access to a drive or drive item (legacy action-based)

    Parameters

    • accessor: Accessor

      Object specifying which entity to grant access to

      • Optionaluser?: string | User
      • Optionalorg_user?: string | OrgUser
      • Optionalagent?: string | Agent
      • Optionalclient?: string | Client
    • action: AccessAction

      The action to grant ('read', 'write', 'delete', or '*' for all)

    Returns Promise<LegacyGrantAccessResponse>

    Promise resolving to the granted permission details

    Deprecated

    Use grantByRole instead for role-based access control Creates a permission that allows the specified accessor to perform the given action on the resource.

    Throws

    If the API request fails

    Example

    Grant read access to a user by ID:

    const drive = await client.drives.get({}, driveId);

    await drive.access.grant(
      { user: 'user123' },
      'read'
    );

    Example

    Grant full access to an agent using model object:

    const agent = await client.agents.get({}, agentId);
    const item = await drive.items.get({}, itemId);

    await item.access.grant(
      { agent: agent },
      '*'
    );

revoke

  • revoke(accessor: Accessor): Promise<RevokeAccessResponse>

    Revoke all access from a drive or drive item

    Removes all permissions that were previously granted to the specified accessor on the resource. All permissions for the accessor are deactivated.

    Parameters

    • accessor: Accessor

      Object specifying which entity to revoke access from

      • Optionaluser?: string | User
      • Optionalorg_user?: string | OrgUser
      • Optionalagent?: string | Agent
      • Optionalclient?: string | Client

    Returns Promise<RevokeAccessResponse>

    Promise resolving to the revocation details including revoked count

    Throws

    If the API request fails

    Example

    Revoke all access from a user by ID:

    const drive = await client.drives.get({}, driveId);

    const result = await drive.access.revoke(
      { org_user: 'orguser123' }
    );
    console.log(`Revoked ${result.revoked_count} permissions`);

    Example

    Revoke all access from an agent using model object:

    const agent = await client.agents.get({}, agentId);
    const result = await drive.access.revoke(
      { agent: agent }
    );
    console.log(`Removed ${result.revoked_count} permissions`);

list

  • list(): Promise<ListAccessorsResponse>

    List all accessors and their roles for a drive or drive item

    Retrieves all entities that have been granted access to the resource, along with their assigned roles and permission details.

    Returns Promise<ListAccessorsResponse>

    Promise resolving to the list of accessors with their roles

    Throws

    If the API request fails

    Example

    List all accessors for a drive:

    const drive = await client.drives.get({}, driveId);

    const result = await drive.access.list();
    console.log(`Drive has ${result.accessors.length} accessors`);

    result.accessors.forEach(accessor => {
      console.log(`${accessor.accessor_type}: ${accessor.accessor_id} - ${accessor.role}`);
    });

    Example

    List all accessors for a drive item:

    const item = await drive.items.get({}, itemId);

    const result = await item.access.list();
    result.accessors.forEach(accessor => {
      console.log(`${accessor.accessor_type} ${accessor.accessor_id} has ${accessor.role} role`);
    });

Settings

Member Visibility

On This Page

Constructors
Methods