Endpoint

/v2/smb/shares/

GET

List all SMB shares. Refer to the 'Modify SMB Share' method for a description of the returned fields.

Parameters

Name Description Required
populate-trustee-names Populate trustee names in the response. By default, trustee names are not returned. No

Response

Codes

Code Description
200 Return value on success

Schema

{
  "type": "array",
  "items": {
    "description": "api_smb_share_v2",
    "type": "object",
    "properties": {
      "id": {
        "description": "The unique ID of the SMB share",
        "type": "string"
      },
      "share_name": {
        "description": "The SMB share name",
        "type": "string"
      },
      "fs_path": {
        "description": "The filesystem path to SMB share",
        "type": "string"
      },
      "description": {
        "description": "Description of this SMB share",
        "type": "string"
      },
      "permissions": {
        "type": "array",
        "items": {
          "description": "The access control list (ACL) for this SMB share",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "ALLOWED",
                "DENIED"
              ],
              "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
            },
            "trustee": {
              "description": "User/group to apply the permissions entry to",
              "type": "object",
              "properties": {
                "domain": {
                  "type": "string",
                  "enum": [
                    "LOCAL",
                    "API_NULL_DOMAIN",
                    "WORLD",
                    "POSIX_USER",
                    "POSIX_GROUP",
                    "ACTIVE_DIRECTORY",
                    "API_INVALID_DOMAIN",
                    "API_RESERVED_DOMAIN",
                    "API_INTERNAL_DOMAIN",
                    "API_OPERATOR_DOMAIN",
                    "API_CREATOR_DOMAIN"
                  ],
                  "description": "domain:\n * `ACTIVE_DIRECTORY` - ACTIVE_DIRECTORY,\n * `API_CREATOR_DOMAIN` - API_CREATOR_DOMAIN,\n * `API_INTERNAL_DOMAIN` - API_INTERNAL_DOMAIN,\n * `API_INVALID_DOMAIN` - API_INVALID_DOMAIN,\n * `API_NULL_DOMAIN` - API_NULL_DOMAIN,\n * `API_OPERATOR_DOMAIN` - API_OPERATOR_DOMAIN,\n * `API_RESERVED_DOMAIN` - API_RESERVED_DOMAIN,\n * `LOCAL` - LOCAL,\n * `POSIX_GROUP` - POSIX_GROUP,\n * `POSIX_USER` - POSIX_USER,\n * `WORLD` - WORLD"
                },
                "auth_id": {
                  "description": "auth_id",
                  "type": "string"
                },
                "uid": {
                  "description": "uid",
                  "type": "number"
                },
                "gid": {
                  "description": "gid",
                  "type": "number"
                },
                "sid": {
                  "description": "sid",
                  "type": "string"
                },
                "name": {
                  "description": "name",
                  "type": "string"
                }
              }
            },
            "rights": {
              "description": "Rights pertaining to the permissions entry",
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "READ",
                  "WRITE",
                  "CHANGE_PERMISSIONS",
                  "ALL",
                  "READ_DATA",
                  "READ_EA",
                  "READ_ATTR",
                  "READ_ACL",
                  "WRITE_EA",
                  "WRITE_ATTR",
                  "WRITE_ACL",
                  "CHANGE_OWNER",
                  "WRITE_GROUP",
                  "DELETE",
                  "EXECUTE",
                  "MODIFY",
                  "EXTEND",
                  "ADD_FILE",
                  "ADD_SUBDIR",
                  "DELETE_CHILD",
                  "SYNCHRONIZE"
                ],
                "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
              }
            }
          }
        }
      },
      "network_permissions": {
        "type": "array",
        "items": {
          "description": "The network access control list (ACL) for this SMB share. If not specified, the default is to allow any host.",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "ALLOWED",
                "DENIED"
              ],
              "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
            },
            "address_ranges": {
              "type": "array",
              "items": {
                "description": "IP address ranges to apply permissions to. Empty means all hosts.",
                "type": "string"
              }
            },
            "rights": {
              "description": "Rights pertaining to the permissions entry",
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "READ",
                  "WRITE",
                  "CHANGE_PERMISSIONS",
                  "ALL",
                  "READ_DATA",
                  "READ_EA",
                  "READ_ATTR",
                  "READ_ACL",
                  "WRITE_EA",
                  "WRITE_ATTR",
                  "WRITE_ACL",
                  "CHANGE_OWNER",
                  "WRITE_GROUP",
                  "DELETE",
                  "EXECUTE",
                  "MODIFY",
                  "EXTEND",
                  "ADD_FILE",
                  "ADD_SUBDIR",
                  "DELETE_CHILD",
                  "SYNCHRONIZE"
                ],
                "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
              }
            }
          }
        }
      },
      "access_based_enumeration_enabled": {
        "description": "Enable Access-based Enumeration on this SMB share",
        "type": "boolean"
      },
      "default_file_create_mode": {
        "description": "Default POSIX file create mode bits on this SMB share (octal, default 0644 if this field is empty)",
        "type": "string"
      },
      "default_directory_create_mode": {
        "description": "Default POSIX directory create mode bits on this SMB share (octal, default 0755 if this field is empty)",
        "type": "string"
      },
      "bytes_per_sector": {
        "description": "SMB bytes per sector reported to clients. We do not support values other than 512. If specified for put or patch, this must be 512.",
        "type": "string"
      },
      "require_encryption": {
        "description": "Require all traffic to this share to be encrypted. Clients without encryption capabilities will not be able to connect. Default is false if this field is empty.",
        "type": "boolean"
      },
      "tenant_id": {
        "description": "The tenant ID of the tenant that the SMB share is a part of",
        "type": "number"
      }
    }
  }
}

POST

Add an SMB share with given options.

Parameters

Name Description Required
allow-fs-path-create Specifies whether the file system path can be created if it does not already exist. No

Request

Schema

{
  "description": "api_smb_share_post_v2",
  "type": "object",
  "properties": {
    "share_name": {
      "description": "The SMB share name",
      "type": "string"
    },
    "fs_path": {
      "description": "The filesystem path to SMB share",
      "type": "string"
    },
    "description": {
      "description": "Description of this SMB share",
      "type": "string"
    },
    "permissions": {
      "type": "array",
      "items": {
        "description": "The access control list (ACL) for this SMB share",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ALLOWED",
              "DENIED"
            ],
            "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
          },
          "trustee": {
            "description": "User/group to apply the permissions entry to",
            "type": "object",
            "properties": {
              "domain": {
                "type": "string",
                "enum": [
                  "LOCAL",
                  "API_NULL_DOMAIN",
                  "WORLD",
                  "POSIX_USER",
                  "POSIX_GROUP",
                  "ACTIVE_DIRECTORY",
                  "API_INVALID_DOMAIN",
                  "API_RESERVED_DOMAIN",
                  "API_INTERNAL_DOMAIN",
                  "API_OPERATOR_DOMAIN",
                  "API_CREATOR_DOMAIN"
                ],
                "description": "domain:\n * `ACTIVE_DIRECTORY` - ACTIVE_DIRECTORY,\n * `API_CREATOR_DOMAIN` - API_CREATOR_DOMAIN,\n * `API_INTERNAL_DOMAIN` - API_INTERNAL_DOMAIN,\n * `API_INVALID_DOMAIN` - API_INVALID_DOMAIN,\n * `API_NULL_DOMAIN` - API_NULL_DOMAIN,\n * `API_OPERATOR_DOMAIN` - API_OPERATOR_DOMAIN,\n * `API_RESERVED_DOMAIN` - API_RESERVED_DOMAIN,\n * `LOCAL` - LOCAL,\n * `POSIX_GROUP` - POSIX_GROUP,\n * `POSIX_USER` - POSIX_USER,\n * `WORLD` - WORLD"
              },
              "auth_id": {
                "description": "auth_id",
                "type": "string"
              },
              "uid": {
                "description": "uid",
                "type": "number"
              },
              "gid": {
                "description": "gid",
                "type": "number"
              },
              "sid": {
                "description": "sid",
                "type": "string"
              },
              "name": {
                "description": "name",
                "type": "string"
              }
            }
          },
          "rights": {
            "description": "Rights pertaining to the permissions entry",
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "READ",
                "WRITE",
                "CHANGE_PERMISSIONS",
                "ALL",
                "READ_DATA",
                "READ_EA",
                "READ_ATTR",
                "READ_ACL",
                "WRITE_EA",
                "WRITE_ATTR",
                "WRITE_ACL",
                "CHANGE_OWNER",
                "WRITE_GROUP",
                "DELETE",
                "EXECUTE",
                "MODIFY",
                "EXTEND",
                "ADD_FILE",
                "ADD_SUBDIR",
                "DELETE_CHILD",
                "SYNCHRONIZE"
              ],
              "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
            }
          }
        }
      }
    },
    "network_permissions": {
      "type": "array",
      "items": {
        "description": "The network access control list (ACL) for this SMB share. If not specified, the default is to allow any host.",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ALLOWED",
              "DENIED"
            ],
            "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
          },
          "address_ranges": {
            "type": "array",
            "items": {
              "description": "IP address ranges to apply permissions to. Empty means all hosts.",
              "type": "string"
            }
          },
          "rights": {
            "description": "Rights pertaining to the permissions entry",
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "READ",
                "WRITE",
                "CHANGE_PERMISSIONS",
                "ALL",
                "READ_DATA",
                "READ_EA",
                "READ_ATTR",
                "READ_ACL",
                "WRITE_EA",
                "WRITE_ATTR",
                "WRITE_ACL",
                "CHANGE_OWNER",
                "WRITE_GROUP",
                "DELETE",
                "EXECUTE",
                "MODIFY",
                "EXTEND",
                "ADD_FILE",
                "ADD_SUBDIR",
                "DELETE_CHILD",
                "SYNCHRONIZE"
              ],
              "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
            }
          }
        }
      }
    },
    "access_based_enumeration_enabled": {
      "description": "Enable Access-based Enumeration on this SMB share",
      "type": "boolean"
    },
    "default_file_create_mode": {
      "description": "Default POSIX file create mode bits on this SMB share (octal, default 0644 if this field is empty)",
      "type": "string"
    },
    "default_directory_create_mode": {
      "description": "Default POSIX directory create mode bits on this SMB share (octal, default 0755 if this field is empty)",
      "type": "string"
    },
    "bytes_per_sector": {
      "description": "SMB bytes per sector reported to clients. We do not support values other than 512. If specified, this must be 512.",
      "type": "string"
    },
    "require_encryption": {
      "description": "Require all traffic to this share to be encrypted. Clients without encryption capabilities will not be able to connect. Default is false if this field is empty.",
      "type": "boolean"
    }
  }
}

Response

Codes

Code Description
200 Return value on success

Schema

{
  "description": "api_smb_share_v2",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique ID of the SMB share",
      "type": "string"
    },
    "share_name": {
      "description": "The SMB share name",
      "type": "string"
    },
    "fs_path": {
      "description": "The filesystem path to SMB share",
      "type": "string"
    },
    "description": {
      "description": "Description of this SMB share",
      "type": "string"
    },
    "permissions": {
      "type": "array",
      "items": {
        "description": "The access control list (ACL) for this SMB share",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ALLOWED",
              "DENIED"
            ],
            "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
          },
          "trustee": {
            "description": "User/group to apply the permissions entry to",
            "type": "object",
            "properties": {
              "domain": {
                "type": "string",
                "enum": [
                  "LOCAL",
                  "API_NULL_DOMAIN",
                  "WORLD",
                  "POSIX_USER",
                  "POSIX_GROUP",
                  "ACTIVE_DIRECTORY",
                  "API_INVALID_DOMAIN",
                  "API_RESERVED_DOMAIN",
                  "API_INTERNAL_DOMAIN",
                  "API_OPERATOR_DOMAIN",
                  "API_CREATOR_DOMAIN"
                ],
                "description": "domain:\n * `ACTIVE_DIRECTORY` - ACTIVE_DIRECTORY,\n * `API_CREATOR_DOMAIN` - API_CREATOR_DOMAIN,\n * `API_INTERNAL_DOMAIN` - API_INTERNAL_DOMAIN,\n * `API_INVALID_DOMAIN` - API_INVALID_DOMAIN,\n * `API_NULL_DOMAIN` - API_NULL_DOMAIN,\n * `API_OPERATOR_DOMAIN` - API_OPERATOR_DOMAIN,\n * `API_RESERVED_DOMAIN` - API_RESERVED_DOMAIN,\n * `LOCAL` - LOCAL,\n * `POSIX_GROUP` - POSIX_GROUP,\n * `POSIX_USER` - POSIX_USER,\n * `WORLD` - WORLD"
              },
              "auth_id": {
                "description": "auth_id",
                "type": "string"
              },
              "uid": {
                "description": "uid",
                "type": "number"
              },
              "gid": {
                "description": "gid",
                "type": "number"
              },
              "sid": {
                "description": "sid",
                "type": "string"
              },
              "name": {
                "description": "name",
                "type": "string"
              }
            }
          },
          "rights": {
            "description": "Rights pertaining to the permissions entry",
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "READ",
                "WRITE",
                "CHANGE_PERMISSIONS",
                "ALL",
                "READ_DATA",
                "READ_EA",
                "READ_ATTR",
                "READ_ACL",
                "WRITE_EA",
                "WRITE_ATTR",
                "WRITE_ACL",
                "CHANGE_OWNER",
                "WRITE_GROUP",
                "DELETE",
                "EXECUTE",
                "MODIFY",
                "EXTEND",
                "ADD_FILE",
                "ADD_SUBDIR",
                "DELETE_CHILD",
                "SYNCHRONIZE"
              ],
              "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
            }
          }
        }
      }
    },
    "network_permissions": {
      "type": "array",
      "items": {
        "description": "The network access control list (ACL) for this SMB share. If not specified, the default is to allow any host.",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ALLOWED",
              "DENIED"
            ],
            "description": "Type of permissions entry (ALLOWED or DENIED):\n * `ALLOWED` - The permissions entry rights are allowed to the trustee,\n * `DENIED` - The permissions entry rights are denied to the trustee"
          },
          "address_ranges": {
            "type": "array",
            "items": {
              "description": "IP address ranges to apply permissions to. Empty means all hosts.",
              "type": "string"
            }
          },
          "rights": {
            "description": "Rights pertaining to the permissions entry",
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "READ",
                "WRITE",
                "CHANGE_PERMISSIONS",
                "ALL",
                "READ_DATA",
                "READ_EA",
                "READ_ATTR",
                "READ_ACL",
                "WRITE_EA",
                "WRITE_ATTR",
                "WRITE_ACL",
                "CHANGE_OWNER",
                "WRITE_GROUP",
                "DELETE",
                "EXECUTE",
                "MODIFY",
                "EXTEND",
                "ADD_FILE",
                "ADD_SUBDIR",
                "DELETE_CHILD",
                "SYNCHRONIZE"
              ],
              "description": "Rights pertaining to the permissions entry:\n * `ADD_FILE` - File creation access,\n * `ADD_SUBDIR` - Directory creation access,\n * `ALL` - All access rights,\n * `CHANGE_OWNER` - Owner write access,\n * `CHANGE_PERMISSIONS` - Rights to change permissions on file objects,\n * `DELETE` - Delete access,\n * `DELETE_CHILD` - Delete from directory access,\n * `EXECUTE` - Execute access,\n * `EXTEND` - File extension access,\n * `MODIFY` - File modification access,\n * `READ` - Read access rights,\n * `READ_ACL` - ACL read access,\n * `READ_ATTR` - Attribute read access,\n * `READ_DATA` - File read access,\n * `READ_EA` - Extended attribute read access,\n * `SYNCHRONIZE` - File synchronize access,\n * `WRITE` - Write access rights,\n * `WRITE_ACL` - ACL write access,\n * `WRITE_ATTR` - Attribute write access,\n * `WRITE_EA` - Extended attribute write access,\n * `WRITE_GROUP` - Group write access"
            }
          }
        }
      }
    },
    "access_based_enumeration_enabled": {
      "description": "Enable Access-based Enumeration on this SMB share",
      "type": "boolean"
    },
    "default_file_create_mode": {
      "description": "Default POSIX file create mode bits on this SMB share (octal, default 0644 if this field is empty)",
      "type": "string"
    },
    "default_directory_create_mode": {
      "description": "Default POSIX directory create mode bits on this SMB share (octal, default 0755 if this field is empty)",
      "type": "string"
    },
    "bytes_per_sector": {
      "description": "SMB bytes per sector reported to clients. We do not support values other than 512. If specified for put or patch, this must be 512.",
      "type": "string"
    },
    "require_encryption": {
      "description": "Require all traffic to this share to be encrypted. Clients without encryption capabilities will not be able to connect. Default is false if this field is empty.",
      "type": "boolean"
    },
    "tenant_id": {
      "description": "The tenant ID of the tenant that the SMB share is a part of",
      "type": "number"
    }
  }
}