> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.
# List directories
`GET /api/web/v1/directories`
List all directories. Caller requires the DIRECTORIES:VIEW permission.
The following attributes are not included in the returned Directory object: directoryAttributeMappings, directorySync, groupFilters, searchBases. The get directory API can be used to acquire these attribute for a specific directory.
## Responses
### 200
Successful
#### application/json
Schema
```json
{
"type": "array",
"items": {
"type": "object",
"properties": {
"aliasMappingName": {
"type": "string",
"description": "The name of the AD attribute value that will be mapped into comma seperated string value of alias",
"example": "adminDescription,adminDisplayName"
},
"certificate": {
"type": "string",
"description": "The SSL certificate to connect to the Directory with.",
"format": "byte",
"deprecated": true
},
"directoryAttributeMappings": {
"type": "array",
"description": "Directory attribure mappings.",
"items": {
"type": "object",
"properties": {
"directoryAttributeName": {
"type": "string",
"description": "The name of the directory attribute being mapped.",
"example": "givenName"
},
"directoryId": {
"type": "string",
"description": "The UUID of the Directory the attribute mapping belongs to.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"id": {
"type": "string",
"description": "The UUID of the attribute mapping.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"userAttribute": {
"required": [
"mandatory",
"name",
"systemDefined",
"unique"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The UUID for this user attribute. Generated when the user attribute is created."
},
"mandatory": {
"type": "boolean",
"description": "A flag indicating if users must have a value for this user attribute."
},
"name": {
"type": "string",
"description": "The name of this user attribute."
},
"systemDefined": {
"type": "boolean",
"description": "A flag indicating if this user attribute is one of the system defined user attributes."
},
"type": {
"type": "string",
"description": "Type of user attribute. Currently only used to specify the type of contact if the attribute is to be used for OTP delivery.",
"example": "OTP_EMAIL",
"enum": [
"NONE",
"OTP_EMAIL",
"OTP_SMS",
"OTP_VOICE",
"OTP_WECHAT",
"OTP_WHATSAPP"
]
},
"unique": {
"type": "boolean",
"description": "A flag indicating if this attribute is intended to be unique."
}
},
"description": "Information about user attribute definitions.",
"title": "UserAttribute"
},
"userAttributeId": {
"type": "string",
"description": "The UUID of the Identity as a Service User Attribute being mapped to.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
}
},
"description": "A DirectoryAttributeMapping defines the information returned about a directory attribute mapping. A directory attribute mapping specifies which directory attribute values are mapped into which Identity as a Service user attributes.",
"title": "DirectoryAttributeMapping"
}
},
"directoryConnections": {
"type": "array",
"description": "The connections that you want to connect when syncing.",
"items": {
"type": "object",
"properties": {
"certificate": {
"type": "string",
"description": "The SSL certificate to connect to the Directory with.",
"format": "byte",
"deprecated": true
},
"directoryId": {
"type": "string",
"description": "The UUID of the Directory the connection belongs to.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"hostname": {
"type": "string",
"description": "The Directory hostname or IP address.",
"example": "10.4.1.2 or directory.server.com"
},
"id": {
"type": "string",
"description": "The UUID of the Directory connection."
},
"port": {
"type": "integer",
"description": "The Directory port.",
"format": "int32",
"example": 389
},
"useSsl": {
"type": "boolean",
"description": "Whether or not to connect to the Directory using an SSL certificate."
}
},
"description": "The connections that you want to connect when syncing.",
"title": "DirectoryConnection"
}
},
"directorySync": {
"type": "object",
"properties": {
"crawlFrequency": {
"type": "integer",
"description": "The rate at which the directory will be queried in milliseconds",
"format": "int32",
"example": 3600000
},
"deltaCrawl": {
"type": "boolean",
"description": "Only sync changed users/groups (delta sync) on next crawl."
},
"directory": "circular(Directory)",
"directoryId": {
"type": "string",
"description": "The ID of the directory."
},
"directorySyncAgentId": {
"type": "string",
"description": "The UUID of the Directory Sync Gateway Agent.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"forceCrawlSequence": {
"type": "integer",
"description": "Sequence counter incremented on each force crawl to trigger agent sync.",
"format": "int32"
},
"groupDesyncPolicy": {
"type": "string",
"description": "Group desynchronization will be done based on the selected option.",
"example": "GROUP_DELETED",
"enum": [
"GROUP_LOCALLY_MANAGED",
"GROUP_DELETED"
]
},
"groupNameAttribute": {
"type": "string",
"description": "The group name attribute"
},
"groupObjectClass": {
"type": "string",
"description": "The Group Object Class",
"example": "groupOfNames"
},
"groupSynchronizationType": {
"type": "string",
"description": "Group synchronization will be done based on the selected option.",
"example": "ALL, FILTER or NONE",
"enum": [
"ALL",
"FILTER",
"NONE"
]
},
"id": {
"type": "string",
"description": "The UUID of the directory.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"lastUpdate": {
"type": "string",
"description": "The last time the directory was updated.",
"format": "date-time",
"example": "2019-02-19T13:15:27Z"
},
"pageSize": {
"type": "integer",
"description": "The number of records that should returned per query. Default is 25.",
"format": "int32",
"example": 25
},
"state": {
"type": "string",
"description": "The status of the Directory Sync.",
"example": "CRAWLING",
"enum": [
"UNKNOWN",
"ERROR",
"PENDING_CHANGES",
"SYNCED",
"OUT_OF_SYNC",
"CRAWLING",
"CRAWL_COMPLETE",
"NOTIFYING_GROUPS",
"NOTIFYING_GROUPS_USERS",
"NOTIFYING_USERS",
"NOTIFY_COMPLETE",
"SYNCING",
"FAILED"
]
},
"userDesyncPolicy": {
"type": "string",
"description": "User synchronization will be done based on the selected option.",
"example": "USER_DELETED",
"enum": [
"USER_LOCALLY_MANAGED_ENABLED",
"USER_LOCALLY_MANAGED_DISABLED",
"USER_DELETED"
]
},
"userObjectClass": {
"type": "string",
"description": "The User Object Class"
},
"userUniqueIdAttribute": {
"type": "string",
"description": "The User Unique Id Attribute"
},
"waitBetweenNotifications": {
"type": "integer",
"description": "How long to wait between notifications in milliseconds.",
"format": "int32",
"example": 500
}
},
"description": "A DirectorySync defines the information returned about the directory sync configuration of a directory.",
"title": "DirectorySync"
},
"directorySyncId": {
"type": "string",
"description": "The UUID of the directory sync",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"groupFilters": {
"type": "array",
"description": "Directory group filters.",
"items": {
"type": "object",
"properties": {
"directoryId": {
"type": "string",
"description": "The UUID of the Directory the group filter belongs to.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"id": {
"type": "string",
"description": "The UUID of the group filter.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"name": {
"type": "string",
"description": "The name of the group to filter on.",
"example": "Engineering"
}
},
"description": "A GroupFilter defines the information returned about a directory group filter.",
"title": "GroupFilter"
}
},
"hostname": {
"type": "string",
"description": "The hostname of the Directory Can be an IP address or a hostname.",
"example": "10.4.1.2 or directory.server.com",
"deprecated": true
},
"id": {
"type": "string",
"description": "The UUID of the Directory.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"name": {
"type": "string",
"description": "The name of the Directory.",
"example": "Directory"
},
"password": {
"type": "string",
"description": "The password to connect to the Directory with."
},
"port": {
"type": "integer",
"description": "The port to connect to the Directory over.",
"format": "int32",
"example": 389,
"deprecated": true
},
"rootDomainNamingContext": {
"type": "string",
"description": "The root domain naming context of the Directory.",
"example": "DC=AnyCorp,DC=biz"
},
"searchBases": {
"type": "array",
"description": "The searchbases that you want to search when syncing.",
"items": {
"type": "object",
"properties": {
"directoryId": {
"type": "string",
"description": "The UUID of the Directory the seachbase belongs to.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"emptySearchBase": {
"type": "boolean",
"description": "Whether or not an empty searchbase is empty?"
},
"id": {
"type": "string",
"description": "The UUID of the searchbase.",
"example": "6781549d-433c-44ea-a42f-4705c26f3245"
},
"node": {
"type": "string",
"description": "The searchbase node.",
"example": "DC=Users"
},
"subsearchbasesIncluded": {
"type": "boolean",
"description": "Whether or not a sub-tree is included?"
}
},
"description": "A SearchBase defines the information returned about a directory search base.",
"title": "SearchBase"
}
},
"type": {
"type": "string",
"description": "The type of the Directory.",
"example": "AD",
"enum": [
"AD",
"LDAP"
]
},
"useSsl": {
"type": "boolean",
"description": "Whether or not to connect to the Directory using an SSL certificate.",
"deprecated": true
},
"userName": {
"type": "string",
"description": "The username to connect to the Directory with. Value must be a fully distinguished name or UPN.",
"example": "CN=Administrator,CN=Users,DC=AnyCorp,DC=biz or Administrator@AnyCorp.biz"
}
},
"description": "A Directory defines the information returned about a directory.",
"title": "Directory"
}
}
```
### 400
Bad Request
#### application/json
Schema
```json
{
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "Error Codes specific to cause of failure.",
"example": "invalid_user_response"
},
"errorMessage": {
"type": "string",
"description": "Additional Error Message describing the error.",
"example": "Application id cannot be null"
},
"parameters": {
"type": "array",
"description": "Optional additional error information.",
"items": {
"type": "object",
"description": "Optional additional error information."
}
}
},
"description": "Object containing information about errors reported by services.",
"title": "ErrorInfo"
}
```
### 401
Access denied
#### application/json
Schema
```json
{
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "Error Codes specific to cause of failure.",
"example": "invalid_user_response"
},
"errorMessage": {
"type": "string",
"description": "Additional Error Message describing the error.",
"example": "Application id cannot be null"
},
"parameters": {
"type": "array",
"description": "Optional additional error information.",
"items": {
"type": "object",
"description": "Optional additional error information."
}
}
},
"description": "Object containing information about errors reported by services.",
"title": "ErrorInfo"
}
```
### 403
Forbidden
#### application/json
Schema
```json
{
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "Error Codes specific to cause of failure.",
"example": "invalid_user_response"
},
"errorMessage": {
"type": "string",
"description": "Additional Error Message describing the error.",
"example": "Application id cannot be null"
},
"parameters": {
"type": "array",
"description": "Optional additional error information.",
"items": {
"type": "object",
"description": "Optional additional error information."
}
}
},
"description": "Object containing information about errors reported by services.",
"title": "ErrorInfo"
}
```
### 404
Not Found
#### application/json
Schema
```json
{
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "Error Codes specific to cause of failure.",
"example": "invalid_user_response"
},
"errorMessage": {
"type": "string",
"description": "Additional Error Message describing the error.",
"example": "Application id cannot be null"
},
"parameters": {
"type": "array",
"description": "Optional additional error information.",
"items": {
"type": "object",
"description": "Optional additional error information."
}
}
},
"description": "Object containing information about errors reported by services.",
"title": "ErrorInfo"
}
```
### 409
Conflict
#### application/json
Schema
```json
{
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"description": "Error Codes specific to cause of failure.",
"example": "invalid_user_response"
},
"errorMessage": {
"type": "string",
"description": "Additional Error Message describing the error.",
"example": "Application id cannot be null"
},
"parameters": {
"type": "array",
"description": "Optional additional error information.",
"items": {
"type": "object",
"description": "Optional additional error information."
}
}
},
"description": "Object containing information about errors reported by services.",
"title": "ErrorInfo"
}
```
## Security
Requirements
```json
[
{
"AdminAPIAuthentication": [
"DIRECTORIES:VIEW"
]
}
]
```