AD Connections

List all AD Connections
Admin roles:
  • access_admin

Lists all AD Connections for your Team

SecuritybearerAuth
Request
path Parameters
team_name
required
string

The name of your Team

query Parameters
offset
string

The UUID of an object used as an offset for pagination

count
integer <int32>

Controls the number of objects listed per page

descending
boolean

If 'true', the most recent results are listed first

prev
boolean

Controls the direction of paging

certificate_id
string

If defined, results only include AD Connections for the specified certificate ID

include_certificate_details
boolean

If 'true', results include any available certificate details for the returned AD Connections

Responses
200

OK

get/v1/teams/{team_name}/integrations/ad_connections
Request samples 
Response samples 
application/json
{
  • "list": [
    • {
      }
    ]
}
Create an AD Connection
Admin roles: 
  • access_admin
Creates an AD Connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
Request Body schema: application/json
required
domain
required
string
The domain to query


 
domain_controllers
Array of strings or null
A comma-separated list of domain controllers used to query the domain. Can use a hostname or IP address.


 
gateway_id
required
string <regex> ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-...
The UUID of a Gateway


 
name
required
string  <= 255 characters 
The name of the AD Connection


 
service_account_password
string or null  <= 255 characters 
The password of the service account


 
service_account_username
string or null  <= 255 characters 
The username of a service account used to query the domain


 
Responses 
201
Created


post/v1/teams/{team_name}/integrations/ad_connections
Request samples 
application/json
{
  • "domain": "foo.example.com",
  • "domain_controllers": [
    • "1.2.3.4",
    • "bar.example.com"
    ],
  • "gateway_id": "5a3af768-063f-4a12-a056-8ef24e555555",
  • "name": "test",
  • "service_account_password": "p@$$w0rD",
  • "service_account_username": "admin"
}
Response samples 
application/json
{
  • "domain": "foo.example.com",
  • "domain_controllers": [
    • "1.2.3.4",
    • "bar.example.com"
    ],
  • "gateway_id": "5a3af768-063f-4a12-a056-8ef24e555555",
  • "id": "99006ae2-db7e-4735-b6bc-c726e6ae81c4",
  • "name": "test",
  • "service_account_username": "admin"
}
Retrieve an AD Connection
Admin roles: 
  • access_admin
Retrieves the properties of a specified AD Connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of the AD Connection


 
Responses 
200
OK


get/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}
Request samples 
Response samples 
application/json
{
  • "active_task_settings_id": "5a3af768-063f-4a12-a056-8ef24e123483",
  • "domain": "foo.example.com",
  • "domain_controllers": [
    • "1.2.3.4",
    • "bar.example.com"
    ],
  • "gateway_id": "5a3af768-063f-4a12-a056-8ef24e555555",
  • "gateway_name": "gateway1",
  • "id": "99006ae2-db7e-4735-b6bc-c726e6ae81c4",
  • "name": "test",
  • "service_account_username": "admin"
}
Update an AD Connection
Admin roles: 
  • access_admin
Updates the properties of a specified AD Connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of the AD Connection


 
Request Body schema: application/json
required
domain
required
string
The domain to query


 
domain_controllers
Array of strings or null
A comma-separated list of domain controllers used to query the domain. Can use a hostname or IP address.


 
gateway_id
required
string <regex> ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-...
The UUID of a Gateway


 
name
required
string  <= 255 characters 
The name of the AD Connection


 
service_account_password
string or null  <= 255 characters 
The password of the service account


 
service_account_username
string or null  <= 255 characters 
The username of a service account used to query the domain


 
Responses 
204
No Content


put/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}
Request samples 
application/json
{
  • "domain": "foo.example.com",
  • "domain_controllers": [
    • "1.2.3.4",
    • "bar.example.com"
    ],
  • "gateway_id": "5a3af768-063f-4a12-a056-8ef24e555555",
  • "name": "test",
  • "service_account_password": "p@$$w0rD",
  • "service_account_username": "admin"
}
Delete an AD Connection
Admin roles: 
  • access_admin
Deletes a specified AD Connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of the AD Connection


 
Responses 
204
No Content


delete/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}
Request samples 
List all AD Server Sync Jobs
Lists all server sync jobs for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
Responses 
200
OK


get/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/task_settings
Request samples 
Response samples 
application/json
{
  • "list": [
    • {
      }
    ]
}
Create a Server Sync Job
Creates a server sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
Request Body schema: application/json
access_address_attribute
string
The AD attribute that defines an IP address or DNS name for a server. This is used by the Gateway to connect to discovered servers.


 
object
Additional AD attributes used to map information to specified labels


 
label
string
An existing ASA label


 
value
string
The AD attribute to map to the specified ASA label


 
alt_names_attributes
string
The AD attribute that defines alternative hostnames or DNS entries. These are used to resolve discovered servers.


 
bastion_attribute
string
The AD attribute that defines the bastion host for a server. Clients use this bastion to tunnel traffic to discovered servers.


 
frequency
string
Indicates how often the server sync job runs. Possible values: 1, 6, 12, 24.


 
host_name_attribute
string
The AD attribute that defines the hostname for a server. This is used to identify discovered servers.


 
id
string <regex> ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-...
The UUID of the server sync job


 
is_active
boolean
If true, enables the server sync job


 
is_guid
boolean
If true, the AD attribute is identified as a Globally Unique Identifier (GUID)


 
name
string
The name of the server sync job


 
os_attribute
string
The AD attribute that defines the operating system of discovered servers


 
object
The rules used to assign discovered servers to Projects


 
base_dn
string
The domain to search for servers


 
ldap_query_filter
string
Defines the criteria used to filter discovered servers


 
priority
string
The priority of this rule assignment


 
project_id
string
The UUID for an existing Project. Discovered servers that match the rules are assigned to this Project


 
start_hour_utc
string
A UTC timestamp that indicates the hour range when the server sync job runs. Only used if frequencyis set to 24.


 
Responses 
201
Created


post/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/task_settings
Request samples 
application/json
{
  • "access_address_attribute": "access_address",
  • "additional_attribute_mapping": {
    • "label": "region",
    • "value": "server_region"
    },
  • "alt_names_attributes": "alt_name",
  • "bastion_attribute": "bastion",
  • "frequency": 24,
  • "host_name_attribute": "host_name",
  • "id": "229a1621-a1g2-6366-q84d-da4vf2e76t2b",
  • "is_active": true,
  • "is_guid": true,
  • "name": "Server Sync Job - 1",
  • "os_attribute": "os",
  • "rule_assignments": {
    • "base_dn": "string",
    • "ldap_query_filter": "string",
    • "priority": "string",
    • "project_id": "string"
    },
  • "start_hour_utc": "2022-08-24T14:15:22Z"
}
Response samples 
application/json
{
  • "access_address_attribute": "access_address",
  • "additional_attribute_mapping": {
    • "label": "region",
    • "value": "server_region"
    },
  • "alt_names_attributes": "alt_name",
  • "bastion_attribute": "bastion",
  • "frequency": 24,
  • "host_name_attribute": "host_name",
  • "id": "229a1621-a1g2-6366-q84d-da4vf2e76t2b",
  • "is_active": true,
  • "is_guid": true,
  • "name": "Server Sync Job - 1",
  • "os_attribute": "os",
  • "recent_task_result": {
    • "ad_task_settings_id": "229a1621-a1g2-6366-q84d-da4vf2e76t2b",
    • "ad_task_settings_name": "Server Sync Job - 1",
    • "ad_test_request_id": "string",
    • "created_at": "2022-08-25T00:00:00Z",
    • "id": "p05ty0e4-a7tv-erp0-r6ynh-robt937s84hf",
    • "rules_summary_status": "done",
    • "status": {
      },
    • "task_state": "done",
    • "updated_at": "2022-08-25T00:10:00Z"
    },
  • "rule_assignments": {
    • "base_dn": "string",
    • "ldap_query_filter": "string",
    • "priority": "string",
    • "project_id": "string"
    },
  • "start_hour_utc": "2022-08-24T14:15:22Z"
}
Retrieve a Server Sync Job
Retrieves a server sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_task_settings_id
required
string
The UUID of an existing server sync job


 
Responses 
200
OK


get/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/task_settings/{ad_task_settings_id}
Request samples 
Response samples 
application/json
{
  • "access_address_attribute": "access_address",
  • "additional_attribute_mapping": {
    • "label": "region",
    • "value": "server_region"
    },
  • "alt_names_attributes": "alt_name",
  • "bastion_attribute": "bastion",
  • "frequency": 24,
  • "host_name_attribute": "host_name",
  • "id": "229a1621-a1g2-6366-q84d-da4vf2e76t2b",
  • "is_active": true,
  • "is_guid": true,
  • "name": "Server Sync Job - 1",
  • "os_attribute": "os",
  • "recent_task_result": {
    • "ad_task_settings_id": "229a1621-a1g2-6366-q84d-da4vf2e76t2b",
    • "ad_task_settings_name": "Server Sync Job - 1",
    • "ad_test_request_id": "string",
    • "created_at": "2022-08-25T00:00:00Z",
    • "id": "p05ty0e4-a7tv-erp0-r6ynh-robt937s84hf",
    • "rules_summary_status": "done",
    • "status": {
      },
    • "task_state": "done",
    • "updated_at": "2022-08-25T00:10:00Z"
    },
  • "rule_assignments": {
    • "base_dn": "string",
    • "ldap_query_filter": "string",
    • "priority": "string",
    • "project_id": "string"
    },
  • "start_hour_utc": "2022-08-24T14:15:22Z"
}
Update a Server Sync Job
Updates a server sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_task_settings_id
required
string
The UUID of an existing server sync job


 
Request Body schema: application/json
access_address_attribute
string
The AD attribute that defines an IP address or DNS name for a server. This is used by the Gateway to connect to discovered servers.


 
object
Additional AD attributes used to map information to specified labels


 
label
string
An existing ASA label


 
value
string
The AD attribute to map to the specified ASA label


 
alt_names_attributes
string
The AD attribute that defines alternative hostnames or DNS entries. These are used to resolve discovered servers.


 
bastion_attribute
string
The AD attribute that defines the bastion host for a server. Clients use this bastion to tunnel traffic to discovered servers.


 
frequency
string
Indicates how often the server sync job runs. Possible values: 1, 6, 12, 24.


 
host_name_attribute
string
The AD attribute that defines the hostname for a server. This is used to identify discovered servers.


 
id
string <regex> ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-...
The UUID of the server sync job


 
is_active
boolean
If true, enables the server sync job


 
is_guid
boolean
If true, the AD attribute is identified as a Globally Unique Identifier (GUID)


 
name
string
The name of the server sync job


 
os_attribute
string
The AD attribute that defines the operating system of discovered servers


 
object
The rules used to assign discovered servers to Projects


 
base_dn
string
The domain to search for servers


 
ldap_query_filter
string
Defines the criteria used to filter discovered servers


 
priority
string
The priority of this rule assignment


 
project_id
string
The UUID for an existing Project. Discovered servers that match the rules are assigned to this Project


 
start_hour_utc
string
A UTC timestamp that indicates the hour range when the server sync job runs. Only used if frequencyis set to 24.


 
Responses 
200
OK


put/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/task_settings/{ad_task_settings_id}
Request samples 
application/json
{
  • "access_address_attribute": "access_address",
  • "additional_attribute_mapping": {
    • "label": "region",
    • "value": "server_region"
    },
  • "alt_names_attributes": "alt_name",
  • "bastion_attribute": "bastion",
  • "frequency": 24,
  • "host_name_attribute": "host_name",
  • "id": "229a1621-a1g2-6366-q84d-da4vf2e76t2b",
  • "is_active": true,
  • "is_guid": true,
  • "name": "Server Sync Job - 1",
  • "os_attribute": "os",
  • "rule_assignments": {
    • "base_dn": "string",
    • "ldap_query_filter": "string",
    • "priority": "string",
    • "project_id": "string"
    },
  • "start_hour_utc": "2022-08-24T14:15:22Z"
}
Response samples 
application/json
{
  • "access_address_attribute": "access_address",
  • "additional_attribute_mapping": {
    • "label": "region",
    • "value": "server_region"
    },
  • "alt_names_attributes": "alt_name",
  • "bastion_attribute": "bastion",
  • "frequency": 24,
  • "host_name_attribute": "host_name",
  • "id": "229a1621-a1g2-6366-q84d-da4vf2e76t2b",
  • "is_active": true,
  • "is_guid": true,
  • "name": "Server Sync Job - 1",
  • "os_attribute": "os",
  • "recent_task_result": {
    • "ad_task_settings_id": "229a1621-a1g2-6366-q84d-da4vf2e76t2b",
    • "ad_task_settings_name": "Server Sync Job - 1",
    • "ad_test_request_id": "string",
    • "created_at": "2022-08-25T00:00:00Z",
    • "id": "p05ty0e4-a7tv-erp0-r6ynh-robt937s84hf",
    • "rules_summary_status": "done",
    • "status": {
      },
    • "task_state": "done",
    • "updated_at": "2022-08-25T00:10:00Z"
    },
  • "rule_assignments": {
    • "base_dn": "string",
    • "ldap_query_filter": "string",
    • "priority": "string",
    • "project_id": "string"
    },
  • "start_hour_utc": "2022-08-24T14:15:22Z"
}
Remove a Server Sync Job
Removes a server sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_task_settings_id
required
string
The UUID of an existing server sync job


 
Responses 
204
No Content


delete/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/task_settings/{ad_task_settings_id}
Request samples 
Deactivate a Server Sync Job
Deactivates an Active Directory server sync job


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_task_settings_id
required
string
The UUID of an existing server sync job


 
Responses 
204
No Content


post/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/task_settings/{ad_task_settings_id}/deactivate
Request samples 
Update a Server Sync Job Schedule
Updates the schedule for a server sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_task_settings_id
required
string
The UUID of an existing server sync job


 
Request Body schema: application/json
frequency
string
Indicates how often the sync job runs. Possible values: 1, 6, 12, 24.


 
start_hour_utc
string
A UTC timestamp that indicates the hour range when the sync job runs. Only used if frequency is set to 24.


 
Responses 
204
No Content


post/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/task_settings/{ad_task_settings_id}/schedule
Request samples 
application/json
{
  • "frequency": 24,
  • "start_hour_utc": "2022-08-24T14:15:22Z"
}
List all AD Server Sync Job Results
Lists all results for a specified server sync job


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_task_settings_id
required
string
The UUID of an existing server sync job


 
Responses 
200
OK


get/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/task_settings/{ad_task_settings_id}/task_results
Request samples 
Response samples 
application/json
{
  • "list": [
    • {
      }
    ]
}
Retrieve a Server Sync Job Result
Retrieves the details summary of a specified server sync job


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_task_settings_id
required
string
The UUID of an existing server sync job


 
ad_task_result_id
required
string
The UUID of an existing server sync job run


 
Responses 
200
OK


get/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/task_settings/{ad_task_settings_id}/task_results/{ad_task_result_id}/detailed_summary
Request samples 
Response samples 
application/json
{
  • "ad_task_settings_id": "229a1621-a1g2-6366-q84d-da4vf2e76t2b",
  • "ad_task_settings_name": "Server Sync Job - 1",
  • "ad_test_request_id": "string",
  • "created_at": "2022-08-25T00:00:00Z",
  • "id": "p05ty0e4-a7tv-erp0-r6ynh-robt937s84hf",
  • "rules_summary_status": "done",
  • "status": {
    • "summary": null,
    • "detailed_summary": null
    },
  • "task_state": "done",
  • "updated_at": "2022-08-25T00:10:00Z"
}
Create a Server Sync Test Request
Creates a test request for the specified server sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_task_settings_id
required
string
The UUID of an existing server sync job


 
Responses 
201
Created


post/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/task_settings/{ad_task_settings_id}/test_request
Request samples 
Response samples 
application/json
{
  • "ad_task_settings_id": "229a1621-a1g2-6366-q84d-da4vf2e76t2b",
  • "ad_task_settings_name": "Server Sync Job - 1",
  • "ad_test_request_id": "string",
  • "created_at": "2022-08-25T00:00:00Z",
  • "id": "p05ty0e4-a7tv-erp0-r6ynh-robt937s84hf",
  • "rules_summary_status": "done",
  • "status": {
    • "summary": null,
    • "detailed_summary": null
    },
  • "task_state": "done",
  • "updated_at": "2022-08-25T00:10:00Z"
}
List all AD User Sync Jobs
Lists all user sync jobs for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
Responses 
200
OK


get/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/user_sync_task_settings
Request samples 
Response samples 
application/json
{
  • "list": [
    • {
      }
    ]
}
Create a User Sync Job
Creates a user sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
Request Body schema: application/json
base_dn
string
The domain to search for user accounts


 
frequency
string
Indicates how often the user sync job runs. Possible values: 1, 6, 12, 24.


 
is_active
boolean
If true, enables the user sync job


 
LDAP_query_filter
string
Defines the criteria used to filter user accounts


 
name
string
The name of the user sync job


 
SID_Field
string
The AD attribute that defines the security identifier (SID) for accounts. Most AD tenants use objectSID.


 
start_hour_utc
string
A UTC timestamp that indicates the hour range when the user sync job runs. Only used if frequency is set to 24.


 
UPN_Field
string
The AD attribute that defines the User Principal Name (UPN) for accounts. Most AD tenants use userPrincipalName.


 
Responses 
201
Created


post/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/user_sync_task_settings
Request samples 
application/json
{
  • "base_dn": "string",
  • "frequency": 24,
  • "is_active": true,
  • "LDAP_query_filter": "string",
  • "name": "User Sync Job - 1",
  • "SID_Field": "objectsid",
  • "start_hour_utc": "2022-08-24T14:15:22Z",
  • "UPN_Field": "userprincipalname"
}
Response samples 
application/json
{
  • "base_dn": "string",
  • "frequency": 24,
  • "id": "226a1922-a1c2-4316-b84d-da4vf2e76t2a",
  • "is_active": true,
  • "LDAP_query_filter": "string",
  • "name": "User Sync Job - 1",
  • "recent_task_result": {
    • "ad_user_sync_task_settings_id": "226a1922-a1c2-4316-b84d-da4vf2e76t2a",
    • "ad_user_sync_task_settings_name": "User Sync Job - 1",
    • "ad_user_sync_test_request_id": "string",
    • "created_at": "2022-08-25T00:00:00Z",
    • "id": "195v2024-d7t2-4311-b84d-ha8vj2eb6tsa",
    • "status": {
      },
    • "task_state": "done",
    • "updated_at": "2022-08-25T00:10:00Z"
    },
  • "SID_Field": "objectsid",
  • "start_hour_utc": "2022-08-24T14:15:22Z",
  • "UPN_Field": "userprincipalname"
}
Retrieve a User Sync Job
Retrieves a user sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_user_sync_task_settings_id
required
string
The UUID of an existing user sync job


 
Responses 
200
OK


get/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/user_sync_task_settings/{ad_user_sync_task_settings_id}
Request samples 
Response samples 
application/json
{
  • "base_dn": "string",
  • "frequency": 24,
  • "id": "226a1922-a1c2-4316-b84d-da4vf2e76t2a",
  • "is_active": true,
  • "LDAP_query_filter": "string",
  • "name": "User Sync Job - 1",
  • "recent_task_result": {
    • "ad_user_sync_task_settings_id": "226a1922-a1c2-4316-b84d-da4vf2e76t2a",
    • "ad_user_sync_task_settings_name": "User Sync Job - 1",
    • "ad_user_sync_test_request_id": "string",
    • "created_at": "2022-08-25T00:00:00Z",
    • "id": "195v2024-d7t2-4311-b84d-ha8vj2eb6tsa",
    • "status": {
      },
    • "task_state": "done",
    • "updated_at": "2022-08-25T00:10:00Z"
    },
  • "SID_Field": "objectsid",
  • "start_hour_utc": "2022-08-24T14:15:22Z",
  • "UPN_Field": "userprincipalname"
}
Update a User Sync Job
Updates a user sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_user_sync_task_settings_id
required
string
The UUID of an existing user sync job


 
Request Body schema: application/json
base_dn
string
The domain to search for user accounts


 
frequency
string
Indicates how often the user sync job runs. Possible values: 1, 6, 12, 24.


 
is_active
boolean
If true, enables the user sync job


 
LDAP_query_filter
string
Defines the criteria used to filter user accounts


 
name
string
The name of the user sync job


 
SID_Field
string
The AD attribute that defines the security identifier (SID) for accounts. Most AD tenants use objectSID.


 
start_hour_utc
string
A UTC timestamp that indicates the hour range when the user sync job runs. Only used if frequency is set to 24.


 
UPN_Field
string
The AD attribute that defines the User Principal Name (UPN) for accounts. Most AD tenants use userPrincipalName.


 
Responses 
200
OK


put/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/user_sync_task_settings/{ad_user_sync_task_settings_id}
Request samples 
application/json
{
  • "base_dn": "string",
  • "frequency": 24,
  • "is_active": true,
  • "LDAP_query_filter": "string",
  • "name": "User Sync Job - 1",
  • "SID_Field": "objectsid",
  • "start_hour_utc": "2022-08-24T14:15:22Z",
  • "UPN_Field": "userprincipalname"
}
Response samples 
application/json
{
  • "base_dn": "string",
  • "frequency": 24,
  • "id": "226a1922-a1c2-4316-b84d-da4vf2e76t2a",
  • "is_active": true,
  • "LDAP_query_filter": "string",
  • "name": "User Sync Job - 1",
  • "recent_task_result": {
    • "ad_user_sync_task_settings_id": "226a1922-a1c2-4316-b84d-da4vf2e76t2a",
    • "ad_user_sync_task_settings_name": "User Sync Job - 1",
    • "ad_user_sync_test_request_id": "string",
    • "created_at": "2022-08-25T00:00:00Z",
    • "id": "195v2024-d7t2-4311-b84d-ha8vj2eb6tsa",
    • "status": {
      },
    • "task_state": "done",
    • "updated_at": "2022-08-25T00:10:00Z"
    },
  • "SID_Field": "objectsid",
  • "start_hour_utc": "2022-08-24T14:15:22Z",
  • "UPN_Field": "userprincipalname"
}
Remove a User Sync Job
Removes a user sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_user_sync_task_settings_id
required
string
The UUID of an existing user sync job


 
Responses 
204
No Content


delete/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/user_sync_task_settings/{ad_user_sync_task_settings_id}
Request samples 
Update a User Sync Job Schedule
Updates the schedule for a user sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_user_sync_task_settings_id
required
string
The UUID of an existing user sync job


 
Request Body schema: application/json
base_dn
string
The domain to search for user accounts


 
frequency
string
Indicates how often the user sync job runs. Possible values: 1, 6, 12, 24.


 
is_active
boolean
If true, enables the user sync job


 
LDAP_query_filter
string
Defines the criteria used to filter user accounts


 
name
string
The name of the user sync job


 
SID_Field
string
The AD attribute that defines the security identifier (SID) for accounts. Most AD tenants use objectSID.


 
start_hour_utc
string
A UTC timestamp that indicates the hour range when the user sync job runs. Only used if frequency is set to 24.


 
UPN_Field
string
The AD attribute that defines the User Principal Name (UPN) for accounts. Most AD tenants use userPrincipalName.


 
Responses 
204
No Content


post/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/user_sync_task_settings/{ad_user_sync_task_settings_id}/schedule
Request samples 
application/json
{
  • "base_dn": "string",
  • "frequency": 24,
  • "is_active": true,
  • "LDAP_query_filter": "string",
  • "name": "User Sync Job - 1",
  • "SID_Field": "objectsid",
  • "start_hour_utc": "2022-08-24T14:15:22Z",
  • "UPN_Field": "userprincipalname"
}
Update a User Sync Job State
Updates the state of a user sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_user_sync_task_settings_id
required
string
The UUID of an existing user sync job


 
Request Body schema: application/json
is_active
boolean
If true, enables the user sync job


 
Responses 
204
No Content


post/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/user_sync_task_settings/{ad_user_sync_task_settings_id}/state
Request samples 
application/json
{
  • "is_active": true
}
Create a User Sync Test Request
Creates a test request for the specified user sync job for an Active Directory connection


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_user_sync_task_settings_id
required
string
The UUID of an existing user sync job


 
Responses 
201
Created


post/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/user_sync_task_settings/{ad_user_sync_task_settings_id}/test_request
Request samples 
Response samples 
application/json
{
  • "ad_user_sync_task_settings_id": "226a1922-a1c2-4316-b84d-da4vf2e76t2a",
  • "ad_user_sync_task_settings_name": "User Sync Job - 1",
  • "ad_user_sync_test_request_id": "string",
  • "created_at": "2022-08-25T00:00:00Z",
  • "id": "195v2024-d7t2-4311-b84d-ha8vj2eb6tsa",
  • "status": {
    • "summary": "string",
    • "detailed_summary": "string"
    },
  • "task_state": "done",
  • "updated_at": "2022-08-25T00:10:00Z"
}
List all AD User Sync Job Results
Lists all results for a specified user sync job


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_user_sync_task_settings_id
required
string
The UUID of an existing user sync job


 
Responses 
200
OK


get/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/user_sync_task_settings/{ad_user_sync_task_settings_id}/user_sync_task_results
Request samples 
Response samples 
application/json
{
  • "list": [
    • {
      }
    ]
}
Retrieve a User Sync Job Result
Retrieves the details summary of a specified user sync job


SecuritybearerAuth 
Request 
path Parameters
team_name
required
string
The name of your Team


 
ad_connection_id
required
string
The UUID of an AD connection


 
ad_user_sync_task_settings_id
required
string
The UUID of an existing user sync job


 
ad_user_sync_task_result_id
required
string
The UUID of an existing user sync job run


 
Responses 
200
OK


get/v1/teams/{team_name}/integrations/ad_connections/{ad_connection_id}/user_sync_task_settings/{ad_user_sync_task_settings_id}/user_sync_task_results/{ad_user_sync_task_result_id}/detailed_summary
Request samples 
Response samples 
application/json
{
  • "ad_user_sync_task_settings_id": "226a1922-a1c2-4316-b84d-da4vf2e76t2a",
  • "ad_user_sync_task_settings_name": "User Sync Job - 1",
  • "ad_user_sync_test_request_id": "string",
  • "created_at": "2022-08-25T00:00:00Z",
  • "id": "195v2024-d7t2-4311-b84d-ha8vj2eb6tsa",
  • "status": {
    • "summary": "string",
    • "detailed_summary": "string"
    },
  • "task_state": "done",
  • "updated_at": "2022-08-25T00:10:00Z"
}