Skip to main content

Access Control (REST) API - Windows Domains

This section includes REST APIs for working with Access Control Windows Domain tasks.

Get All Windows Domains - GET /WindowsDomains

Get details of all Windows domains.

Notice

The ‘Manage Authentication Providers’ or ‘Manage System Settings’ permission is required to execute this API.

Usage:

  1. GET /WindowsDomains and get details of all Windows domains

  2. PUT /Users/{id} and update Windows domain details

URL

/cxrestapi/auth/WindowsDomains

Method:

GET

Media Type (header):

Authorization: Bearer <access token value>

Accept: application/json;v=1.0

Parameters

None

Success Response:

Code: 200 Success

Error Response:

Code: 401 Unauthorized

Code: 403 Forbidden

Sample Response:

[
  {
    "id": 1,
    "name": "google",
    "fullyQualifiedName": "google.com"
  },
  {
    "id": 2,
    "name": "microsoft",
    "fullyQualifiedName": "microsoft.com"
  },
  {
    "id": 3,
    "name": "sap",
    "fullyQualifiedName": "sap.com"
  },
  {
    "id": 4,
    "name": "apple",
    "fullyQualifiedName": "apple.com"
  },
  {
    "id": 5,
    "name": "oracle",
    "fullyQualifiedName": "oracle.com"
  }
]

Notes:

Retrieves details of all Windows domains. If the request fails, it returns an error response.

Create a New Windows Domain - POST /WindowsDomains

Create a new Windows domain.

Notice

The ‘Manage Authentication Providers’ or ‘Manage System Settings’ permission is required to execute this API.

Usage:

  1. POST /WindowsDomains and create new Windows domain

  2. GET /WindowsDomains/{id} and get details of a Windows domain

URL

/cxrestapi/auth/WindowsDomains

Method:

POST

Media Type (header):

Authorization: Bearer <access token value>

Content-Type: application/json;v=1.0

Parameters

windowsDomainViewModel=[body]: Specifies the Windows domain details

name=[string] - Windows domain name

Success Response:

Code: 201 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Sample Response:

no content

Notes:

Returns the location of the created Windows domain in the response header. If the request fails, it returns an error response.

Get Windows Domain by Id - GET /WindowsDomains/{id}

Get details of a Windows domain according to Windows Domain Id.

Notice

The ‘Manage Authentication Providers’ or ‘Manage System Settings’ permission is required to execute this API.

Usage:

  1. POST /WindowsDomains and create new Windows domain

  2. GET /WindowsDomains/{id} and get details of a Windows domain

URL

/cxrestapi/auth/WindowsDomains/{id}

Method:

GET

Media Type (header):

Authorization: Bearer <access token value>

Accept: application/json;v=1.0

Parameters

Required:

id=[integer] – Unique Id of the Windows domain

Success Response:

Code: 200 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not Found

Sample Response:

{

"id": 1,

"name": "dm",

"fullyQualifiedName": "dm.cx"

}

Notes:

Retrieves details of the Windows domain according to the specified Windows domain Id. If the request fails, it returns an error response.

Update a Windows Domain - PUT /WindowsDomains/{id}

Update Windows domain details according to Windows Domain Id.

Notice

The ‘Manage Authentication Providers’ or ‘Manage System Settings’ permission is required to execute this API.

Usage:

  1. GET /WindowsDomains/{id} and get details of a Windows domain

  2. PUT /Users/{id} and update Windows domain details

URL

/cxrestapi/auth/WindowsDomains/{id}

Method:

PUT

Media Type (header):

Authorization: Bearer <access token value>

Content-Type: application/json;v=1.0

Parameters

Required:

id=[integer] - Unique Id of the Windows domain

windowsDomainViewModel=[body]: Specifies the Windows domain details to update

name=[string] - Windows domain name. The domain name is used to authenticate a user (i.e., domain\username)

fullyQualifiedName=[string] - Windows domain fully qualified name. Used to verify that an LDAP user exist in the relevant domain

Success Response:

Code: 204 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not Found

Sample Response:

no content

Notes:

Updates the Windows domain details according to the defined parameters. Once the request is successful, it does not return any content. If the request fails, it returns an error response.

Delete a Windows Domain – DELETE /WindowsDomains/{id}

Delete a Windows domain according to Windows Domain Id. Note that this action permanently deletes all related users.

Notice

The ‘Manage Authentication Providers’ or ‘Manage System Settings’ permission is required to execute this API.

Usage:

  1. GET /WindowsDomains/{id} and get details of a Windows domain

  2. DELETE /WindowsDomains/{id} and delete a Windows domain

URL

/cxrestapi/auth/WindowsDomains/{id}

Method:

DELETE

Media Type (header):

Authorization: Bearer <access token value>

Content-Type: application/json;v=1.0

Parameters

Required:

id=[integer] - Unique Id of the Windows domain

Success Response:

Code: 204 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not Found

Sample Response:

no content

Notes:

Deletes a Windows domain according to the Windows Domain Id. Once the request is successful, it does not return any content. If the request fails, it returns an error response.

Get User Entries by Search Criteria – GET /WindowsDomains/{id}/UserEntries (v2.0 and up)

Get user entries according to specific search criteria.

Notice

The ‘Manage Users‘, Manage Authentication Providers’ or ‘Manage System Settings’ permission is required to execute this API.

Usage:

  1. GET /WindowsDomains/{id}/UserEntries and get user entries according to specific search criteria

  2. POST /Users and create a new user.

URL

cxrestapi/auth/WindowsDomains/{id}/UserEntries

Method:

GET

Media Type (header):

Authorization: Bearer <access token value>

Accept: application/json;v=1.0

Parameters

id=[integer] - Unique Id of the Windows domain

containsPattern=[string] - User name or full name contains pattern (e.g., dm)

Success Response:

Code: 200 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not Found

Sample Response:

[
  {
    "username": "admin",
    "firstname": "Richard",
    "lastname": "Smith",
    "email": "admin@check.org"
  }
]

Notes:

Retrieves user entries according to specific search criteria. If the request fails, it returns an error response.

In this section: