REST API reference | AD Web Docs

Endpoints, parameters and examples for the AD Web REST API, for creating and managing Active Directory users, groups and OUs.

The AD Web REST API lets other systems create and manage Active Directory users, groups and OUs through AD Web. This page lists every endpoint with its parameters and an example call.

Before you begin#

Create an API key pair. See API settings.
Check your API route. The examples use the default route, restapi. If you changed it, use your route instead.

Base URL#

https://adweb.yourdomain.com/restapi/

Replace adweb.yourdomain.com with your AD Web host. The API works over http or https.

Authentication#

Send your key pair in these headers on every request:

Header	Value
`ApiKey`	Your API key.
`ApiSecret`	Your API secret.
`Content-Type`	`application/json` (for requests with a body).

Responses#

All endpoints return the same kind of response.

Result	Status code	Body
Success	`200 OK`	A success message or the result of the request.
Error	`4xx` or `5xx`, depending on the error	An error message, and possibly an error code.

Conventions#

DN means distinguished name, for example cn=micheal,ou=dartians,dc=dart,dc=org.
FQDN is the fully qualified domain name of the Active Directory domain, for example dart.org. It tells AD Web which connected domain to use.

Users#

POST /restapi/createuser#

Creates a user in Active Directory.

Body

Field	Type	Required	Description
`createUser`	object	Yes	The new user. Every field in this object is required.
`createUser.SamAccountName`	string	Yes	The user's SAM account name.
`createUser.UserPrincipalName`	string	Yes	The user's UPN.
`createUser.Password`	string	Yes	The user's password.
`createUser.ouDN`	string	Yes	DN of the OU or container to create the user in.
`createUser.FQDN`	string	Yes	FQDN of the domain.
`customAttributes`	object	No	Values for other Active Directory attributes of the user, as `"attribute": "value"` pairs. Add as many as you need, separated by commas.

Example request

curl --location 'https://adweb.yourdomain.com/restapi/createuser' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "createUser": {
      "SamAccountName": "micheal",
      "UserPrincipalName": "micheal@dart.org",
      "Password": "dummy@assword",
      "ouDN": "CN=Dart,dc=dart,dc=org",
      "FQDN": "dart.org"
    },
    "customAttributes": {
      "pager": "some value"
    }
  }'

PUT /restapi/updateuser#

Updates an Active Directory user's details.

Body

Field	Type	Required	Description
`updateUser`	object	Yes	The user and the fields to change. Only `userDN` and `FQDN` are required; include any other fields you want to change.
`updateUser.userDN`	string	Yes	DN of the user to update.
`updateUser.FQDN`	string	Yes	FQDN of the domain.
`updateUser.SamAccountName`	string	No	New SAM account name.
`updateUser.UserPrincipalName`	string	No	New UPN.
`updateUser.Password`	string	No	New password.
`updateUser.ouDN`	string	No	DN of the OU.
`customAttributes`	object	No	New values for other Active Directory attributes, as `"attribute": "value"` pairs. Add as many as you need, separated by commas.

Example request

curl --location --request PUT 'https://adweb.yourdomain.com/restapi/updateuser' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "updateUser": {
      "userDN": "cn=micheal,ou=dartians,dc=dart,dc=org",
      "SamAccountName": "micheal",
      "UserPrincipalName": "micheal@dart.org",
      "Password": "Abcd$ssw212",
      "ouDN": "ou=abcsite,dc=dart,dc=org",
      "FQDN": "dart.org"
    },
    "customAttributes": {
      "mail": "user@example.com"
    }
  }'

PUT /restapi/enableuser#

Enables an Active Directory user.

Body

Field	Type	Required	Description
`userDN`	string	Yes	DN of the user.
`FQDN`	string	Yes	FQDN of the domain.
`notifyEmail`	boolean	No	Set to `true` to email the user after enabling the account.

Example request

curl --location --request PUT 'https://adweb.yourdomain.com/restapi/enableuser' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "userDN": "cn=micheal,ou=dartians,dc=dart,dc=org",
    "FQDN": "dart.org",
    "notifyEmail": false
  }'

PUT /restapi/disableuser#

Disables an Active Directory user.

Body

Field	Type	Required	Description
`userDN`	string	Yes	DN of the user.
`FQDN`	string	Yes	FQDN of the domain.
`notifyEmail`	boolean	No	Set to `true` to email the user after disabling the account.

Example request

curl --location --request PUT 'https://adweb.yourdomain.com/restapi/disableuser' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "userDN": "cn=micheal,ou=dartians,dc=dart,dc=org",
    "FQDN": "dart.org",
    "notifyEmail": false
  }'

PUT /restapi/unlockuser#

Unlocks a locked Active Directory user.

Body

Field	Type	Required	Description
`userDN`	string	Yes	DN of the user.
`FQDN`	string	Yes	FQDN of the domain.
`notifyEmail`	boolean	No	Set to `true` to email the user after unlocking the account.

Example request

curl --location --request PUT 'https://adweb.yourdomain.com/restapi/unlockuser' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "userDN": "cn=micheal,ou=dartians,dc=dart,dc=org",
    "fqdn": "dart.org",
    "notifyEmail": true
  }'

PUT /restapi/passwordreset#

Resets an Active Directory user's password.

Body

Field	Type	Required	Description
`userDN`	string	Yes	DN of the user.
`FQDN`	string	Yes	FQDN of the domain.
`notifyEmail`	boolean	No	Set to `true` to email the user after the reset.

Example request

curl --location --request PUT 'https://adweb.yourdomain.com/restapi/passwordreset' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "userDN": "cn=micheal,ou=dartians,dc=dart,dc=org",
    "fqdn": "dart.org",
    "notifyEmail": true
  }'

POST /restapi/moveusertoou#

Moves an Active Directory user to another OU.

Body

Field	Type	Required	Description
`userDN`	string	Yes	DN of the user.
`ouDN`	string	Yes	DN of the OU to move the user to.
`fqdn`	string	Yes	FQDN of the domain.

Example request

curl --location 'https://adweb.yourdomain.com/restapi/moveusertoou' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "userDN": "cn=micheal,ou=abc,dc=dart,dc=org",
    "ouDN": "ou=abc-child,ou=abc,dc=dart,dc=org",
    "fqdn": "dart.org"
  }'

POST /restapi/assignusertogroup#

Adds an Active Directory user to a group.

Body

Field	Type	Required	Description
`userDN`	string	Yes	DN of the user.
`groupDN`	string	Yes	DN of the group.
`fqdn`	string	Yes	FQDN of the domain.

Example request

curl --location --request POST 'https://adweb.yourdomain.com/restapi/assignusertogroup' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "userDN": "cn=micheal,ou=abc,dc=dart,dc=org",
    "groupDN": "cn=interfaceadmin,ou=abc,dc=dart,dc=org",
    "fqdn": "dart.org"
  }'

GET /restapi/getuserinfo#

Returns the details of an Active Directory user.

Query parameters

Parameter	Type	Required	Description
`userDN`	string	Yes	DN of the user.
`fqdn`	string	Yes	FQDN of the domain.

Example request

curl --location --get 'https://adweb.yourdomain.com/restapi/getuserinfo' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --data-urlencode 'userDN=cn=micheal,ou=abc-child,dc=dart,dc=org' \
  --data-urlencode 'FQDN=dart.org'

GET /restapi/getusergroupinfo#

Returns the groups an Active Directory user belongs to.

Query parameters

Parameter	Type	Required	Description
`userDN`	string	Yes	DN of the user.
`fqdn`	string	Yes	FQDN of the domain.

Example request

curl --location --get 'https://adweb.yourdomain.com/restapi/getusergroupinfo' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --data-urlencode 'userDN=cn=micheal,ou=abc-child,dc=dart,dc=org' \
  --data-urlencode 'FQDN=dart.org'

GET /restapi/getusers#

Returns all users in an OU or location.

Query parameters

Parameter	Type	Required	Description
`ouDN`	string	Yes	DN of the OU or location.
`fqdn`	string	Yes	FQDN of the domain.

Example request

curl --location --get 'https://adweb.yourdomain.com/restapi/getusers' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --data-urlencode 'ouDN=ou=abc-child,dc=dart,dc=org' \
  --data-urlencode 'FQDN=dart.org'

GET /restapi/getdn#

Returns the distinguished name of a user, group or OU.

Query parameters

Parameter	Type	Required	Description
`samAccountName`	string	Yes	SAM account name of the user, group or OU.
`fqdn`	string	Yes	FQDN of the domain.
`notifyEmail`	string	No	Listed in the source as "send a notification email to the user".

Example request

curl --location --get 'https://adweb.yourdomain.com/restapi/getdn' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --data-urlencode 'samAccountName=micheal' \
  --data-urlencode 'FQDN=dart.org'

Groups#

GET /restapi/getgroupmembers#

Returns the members of an Active Directory group.

Query parameters

Parameter	Type	Required	Description
`groupDN`	string	Yes	DN of the group.
`fqdn`	string	Yes	FQDN of the domain.

Example request

curl --location --get 'https://adweb.yourdomain.com/restapi/getgroupmembers' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --data-urlencode 'groupDN=cn=interfaceadmin,dc=dart,dc=org' \
  --data-urlencode 'FQDN=dart.org'

Organisational units#

POST /restapi/createparentou#

Creates a new top-level OU in Active Directory.

Body

Field	Type	Required	Description
`newOuName`	string	Yes	Name of the new OU.
`description`	string	No	Description of the OU.
`city`	string	No	City of the OU.
`state`	string	No	State of the OU.
`street`	string	No	Street of the OU.
`postalCode`	string	No	Postal code of the OU.
`country`	string	No	Country of the OU.
`fqdn`	string	Yes	FQDN of the domain.
`accidentialDeletion`	boolean	No	Protects the OU from accidental deletion. Shown in the example only.

Example request

curl --location 'https://adweb.yourdomain.com/restapi/createparentou' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "newOuName": "ABC Site",
    "description": "ABC Organization",
    "city": "Newyork",
    "state": "Newyork",
    "street": "1st avenue",
    "postalCode": "54561",
    "country": "United States",
    "fqdn": "dart.org",
    "accidentialDeletion": true
  }'

POST /restapi/createchildou#

Creates a new child OU under an existing OU.

Body

Field	Type	Required	Description
`parentOuDn`	string	Yes	DN of the parent OU.
`newChildOuName`	string	Yes	Name of the new child OU.
`description`	string	No	Description of the OU.
`city`	string	No	City of the OU.
`state`	string	No	State of the OU.
`street`	string	No	Street of the OU.
`postalCode`	string	No	Postal code of the OU.
`country`	string	No	Country of the OU.
`fqdn`	string	Yes	FQDN of the domain.
`accidentialDeletion`	boolean	No	Protects the OU from accidental deletion. Shown in the example only.

Example request

curl --location 'https://adweb.yourdomain.com/restapi/createchildou' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "parentOuDn": "OU=Dart-ABC,DC=dart,DC=org",
    "newChildOuName": "ABC-child",
    "description": "ABC Organization",
    "city": "Newyork",
    "state": "Newyork",
    "street": "1st avenue",
    "postalCode": "54561",
    "country": "United States",
    "fqdn": "dart.org",
    "accidentialDeletion": true
  }'

GET /restapi/getoumembers#

Returns the members of an OU.

Query parameters

Parameter	Type	Required	Description
`ouDN`	string	Yes	DN of the OU.
`fqdn`	string	Yes	FQDN of the domain.

Example request

curl --location --get 'https://adweb.yourdomain.com/restapi/getoumembers' \
  --header 'ApiKey: <your-api-key>' \
  --header 'ApiSecret: <your-api-secret>' \
  --data-urlencode 'ouDN=ou=abc-child,dc=dart,dc=org' \
  --data-urlencode 'FQDN=dart.org'