Help Center/ Scalable File Service Turbo/ API Reference/ API/ Permissions Management/ Joining an AD Domain
Updated on 2025-09-17 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Joining an AD Domain

Function

This API is used to add a file system to an AD domain. Active Directory Domain Services (AD DS) is a directory service that provides unified identity and permissions management through domain networks. By adding an SFS Turbo file system to an AD domain, you can easily authenticate and manage user identities and control file permissions in that domain.

Constraints

This API is only supported for SMB file systems.

URI

POST /v1/{project_id}/sfs-turbo/shares/{share_id}/fs/active-directory-domain

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

The project ID.

share_id

Yes

String

The file system ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

The account token.

Content-Type

Yes

String

The MIME type.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

service_account

Yes

String

The service account, which is specified when the domain server is created. administrator is used normally.

password

Yes

String

The password of the service account.

domain_name

Yes

String

The domain name of the domain controller. It is specified when the domain server is created.

system_name

Yes

String

The name of the file system in the AD domain.

overwrite_same_account

No

Boolean

If the option is enabled and the domain controller already has the file system name you specified, the information you specified will overwrite the existing information in the domain controller.

dns_server

Yes

Array of strings

The IP address of the DNS server. It is used to resolve the AD domain name.

organization_unit

No

String

A group of domain objects, such as users, computers, and printers. If you add the file system to an organizational unit (OU), it will become a member of that OU. If this parameter is left blank, the file system will be added to the computers OU.

vpc_id

No

String

The VPC ID.

Response Parameters

Status code: 202

Table 4 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.
Table 5 Response body parameters

Parameter

Type

Description

job_id

String

The ID of the asynchronous task for joining the AD domain.

Status code: 400

Table 6 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.
Table 7 Response body parameters

Parameter

Type

Description

errCode

String

The error code.

errMsg

String

The error message.

Status code: 500

Table 8 Response header parameters

Parameter

Type

Description

X-request-id

String

The request ID.
Table 9 Response body parameters

Parameter

Type

Description

errCode

String

The error code.

errMsg

String

The error message.

Example Requests

Joining an AD domain

POST HTTPS://{endpoint}/v1/{project_id}/sfs-turbo/shares/{share_id}/fs/active-directory-domain

{
  "service_account" : "administrator",
  "password" : "pwdxxxxx",
  "domain_name" : "SFSTURBO.COM",
  "system_name" : "sfs",
  "dns_server" : "100.xxx:xxx"
}

Example Responses

Status code: 400

Error response

{
  "errCode" : "SFS.TURBO.0001",
  "errMsg" : "parameter domain_name is required and cannot be empty"
}

Status code: 500

Error response

{
  "errCode" : "SFS.TURBO.0005",
  "errMsg" : "Internal server error"
}

Status Codes

Status Code

Description

202

Join request delivered

400

Error response

500

Error response

Error Codes

See Error Codes.

Parent topic: Permissions Management