Support for Server products ended Feb. 15, 2024. Learn what this means for you.

Last updated Dec 8, 2017

Deprecated - Crowd Admin REST resources

The Crowd REST APIs allow you to address the Crowd data entities as 'resources'. This means that they are identified by URIs and operated on by HTTP requests, chiefly GET and POST. Whenever you GET one of these resources, you receive a representation encoded using XML or JSON. Below are details of the resources made available by the APIs.

The Crowd 2.0 experimental REST APIs are deprecated

Crowd 2.0 introduced the experimental 'admin' REST APIs, allowing interactions with the Crowd Administration Console. In the upcoming release of Crowd 2.1, we will replace these with a new set of REST APIs for use by applications connecting to Crowd. This JIRA issue has the details - see the description and the comments: CWD-1912. We will be delighted with your feedback on the JIRA issue too.

Introduction

URI Structure

URIs for a Crowd REST API resource have the following structure: With context:

1
2
http://host:port/context/rest/api-name/api-version/resource-name

Or without context:

1
2
http://host:port/rest/api-name/api-version/resource-name

In Crowd 2.0, the only api-name available is admin. This is the API that allows interaction with the Crowd Administration Console.

**Examples:** With context:

1
2
http://myhost.com:8095/crowd/rest/admin/1/directory
http://localhost:8095/crowd/rest/admin/latest/directory

Or without context:

1
2
http://crowd.myhost.com:8095/rest/admin/1/directory
http://crowd.myhost.com:8095/rest/admin/latest/directory

More...

Please refer to the Crowd REST API usage guide for a description of the common factors in the APIs, including a full explanation of the URI format, authentication, API versions, etc.

Directory List

URI	`/directory`
Description	Lists all the directories managed by the Crowd server.
URI Parameters	None. The directory resource does not currently support the `search` parameter. There is an existing improvement request: CWD-1603
HTTP Methods	`GET` -- Returns a list of directories.

Example of a GET request:

1
2
http://localhost:8095/crowd/rest/admin/latest/directory/

Example of XML response:

1
2
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<directories>
 <directory>
  <name>Active Directory</name> 
  <type>CONNECTOR</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.connector.MicrosoftActiveDirectory</implementationClass> 
  </directory>
 <directory>
  <name>Atlassian Crowd</name> 
  <type>INTERNAL</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.internal.InternalDirectory</implementationClass> 
  </directory>
 <directory>
  <name>Crowd Internal</name> 
  <type>INTERNAL</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.internal.InternalDirectory</implementationClass> 
  </directory>
 <directory>
  <name>Delegated Auth Directory</name> 
  <type>DELEGATING</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.delegated.DelegatedAuthenticationDirectory</implementationClass> 
  </directory>
 <directory>
  <name>Employees</name> 
  <type>INTERNAL</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.internal.InternalDirectory</implementationClass> 
  </directory>
 <directory>
  <name>My Own Connector</name> 
  <type>CUSTOM</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.custom.MyOwnConnector</implementationClass> 
  </directory>
</directories>

Elements in the response:

Element	Description
`directories`	A list of directories defined in Crowd.
	Refer to the section on directory information CROWD:below for the elements describing each directory.

Example of JSON response:

1
2
{"directories":[
{"name":"Active Directory",
"type":"CONNECTOR",
"implementationClass":"com.atlassian.crowd.integration.directory.connector.MicrosoftActiveDirectory"},{"name":"Atlassian Crowd",
"type":"INTERNAL",
"implementationClass":"com.atlassian.crowd.integration.directory.internal.InternalDirectory"},{"name":"Crowd Internal",
"type":"INTERNAL",
"implementationClass":"com.atlassian.crowd.integration.directory.internal.InternalDirectory"},{"name":"Delegated Auth Directory",
"type":"DELEGATING",
"implementationClass":"com.atlassian.crowd.integration.directory.delegated.DelegatedAuthenticationDirectory"},{"name":"Employees",
"type":"INTERNAL",
"implementationClass":"com.atlassian.crowd.integration.directory.internal.InternalDirectory"}
{"name":"My Own Connector",
"type":"CUSTOM",
"implementationClass":"com.atlassian.crowd.integration.directory.custom.MyOwnConnector"}]}

Directory Information

URI	`/directory/DIRECTORY-KEY` where `DIRECTORY-KEY` is the directory name
Description	Retrieves information about a specific directory.
URI Parameters	None.
HTTP Methods	`GET` -- Returns the directory information.

Example of a request for information about directory 'atlassian crowd':

1
2
http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd

Example of XML response:

1
2
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<directory>
  <name>Atlassian Crowd</name> 
  <type>INTERNAL</type> 
  <implementationClass>com.atlassian.crowd.integration.directory.internal.InternalDirectory</implementationClass> 
</directory>

Elements in the response:

Element	Description
`directory`	A directory defined in Crowd.
`name`	The name of the directory, as defined in Crowd.
`type`	The Crowd directory type. Possible values are: `CONNECTOR` -- An LDAP directory connector `INTERNAL` -- A Crowd internal directory `DELEGATING` -- A Delegated Authentication directory `CUSTOM` -- A custom directory connector
`implementationClass`	The Java class file that provides the methods for authentication, searching, and creation, deletion and updating the entities in the directory.

Example of JSON response:

1
2
{"name":"Atlassian Crowd",
"type":"INTERNAL",
"implementationClass":"com.atlassian.crowd.integration.directory.internal.InternalDirectory"}

User List

URI	`/directory/DIRECTORY-KEY/user` where `DIRECTORY-KEY` is the directory name
Description	Lists all the users in the given directory and allows you to add a user to the list.
URI Parameters	`?search=SEARCHVALUE` -- This parameter is required on a `GET` request. This resource returns an HTTP 403 (access forbidden) if a GET request is sent to the URL without the search parameter. Replace `SEARCHVALUE` with your search term. The search term can be all or part of the username, name or email address. Leave the search term empty to return all users. Requesting all users is not recommended if your Crowd installation manages a large number of users, as this can result in severe performance degradation.
HTTP Methods	`GET` -- Returns a list of users. `POST` -- Adds a user to the given directory. For the XML specification, refer to the CROWD:user information resource.

Example of a search for users matching 'ad' in directory 'atlassian crowd':

1
2
http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/user?search=ad

Example of XML response to the above request:

1
2
 <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<users>
 <user>
  <identifier>adent</identifier> 
  <username>adent</username> 
  <firstName>Arthur</firstName> 
  <lastName>Dent</lastName> 
  <displayName>Arthur Dent</displayName> 
  <emailAddress>adent@example.com</emailAddress> 
  </user>
 <user>
  <identifier>admin</identifier> 
  <username>admin</username> 
  <firstName>Admin</firstName> 
  <lastName>Administrator</lastName> 
  <displayName>Admin Administrator</displayName> 
  <emailAddress>admin@example.com</emailAddress> 
  </user>
</users>

Elements in the response:

Element	Description
`users`	A list of users in the Crowd directory.
	Refer to the section on user information CROWD:below for the elements describing each user.

Example of JSON response for a list of users:

1
2
{"users":[
{"identifier":"adent",
"username":"adent",
"firstName":"Arthur",
"lastName":"Dent",
"displayName":"Arthur Dent",
"emailAddress":"adent@example.com"},
{"identifier":"admin",
"username":"admin",
"firstName":"Admin",
"lastName":"Administrator",
"displayName":"Admin Administrator",
"emailAddress":"admin@example.com"}]}

User Information

URI	`/directory/DIRECTORY-KEY/user/USER-KEY` where `DIRECTORY-KEY` is the directory name and `USER-KEY` is the username
Description	Retrieves or updates information about a specific user and allows deletion of the user from the given directory.
URI Parameters	None.
HTTP Methods	`GET` -- Returns information about the given user in the given directory. `PUT` -- Updates the user details. `DELETE` -- Removes the user from the directory.

Here is an example of a request for information on user 'adent' in directory 'atlassian crowd':

1
2
http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/user/adent

The following cURL request deletes the user 'adent', using basic authentication where the username and password are both 'admin':

1
2
curl -X DELETE http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/user/adent -u admin:admin

Example of XML response giving user information:

1
2
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<user>
  <identifier>adent</identifier> 
  <username>adent</username> 
  <firstName>Arthur</firstName> 
  <lastName>Dent</lastName> 
  <displayName>Arthur Dent</displayName> 
  <emailAddress>adent@example.com</emailAddress> 
</user>

Elements in the response:

Element	Description
`user`	A user defined in a Crowd directory.
`identifier`	The user's username. Currently, this element contains the same value as the `username` element.
`username`	The user's username.
`firstName`	The user's first name.
`lastName`	The user's last name.
`displayName`	The user's full name, composed of first name plus last name.
`emailAddress`	The user's email address.

Example of JSON response giving user information:

1
2
{"identifier":"adent",
"username":"adent",
"firstName":"Arthur",
"lastName":"Dent",
"displayName":"Arthur Dent",
"emailAddress":"adent@example.com"}

The following cURL request will add the user represented in a user.xml file to the 'atlassian crowd' directory, using basic authentication where the username and password are both 'admin':

1
2
curl -X POST --data @user.xml http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/user -H "Content-Type: application/xml" -u admin:admin

Sample XML file:

1
2
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user>
    <identifier>ghalfrunt</identifier>
    <username>ghalfrunt</username>
    <firstName>Gag</firstName>
    <lastName>Halfrunt</lastName>
    <displayName>Gag Halfrunt</displayName>
    <emailAddress>ghalfrunt@example.com</emailAddress>
    <password>brains</password>
</user>

If the POST is successful you will receive the CREATED 201 response code.

Group List

URI	`/directory/DIRECTORY-KEY/group` where `DIRECTORY-KEY` is the directory name
Description	Lists all the groups in the given directory.
URI Parameters	`?search=SEARCHVALUE` -- This parameter is required on a `GET` request. This resource returns an HTTP 403 (access forbidden) if a GET request is sent to the URL without the search parameter. Replace `SEARCHVALUE` with your search term. The search term can be all or part of the group name. Leave the search term empty to return all groups.
HTTP Methods	`GET` -- Returns a list of groups. `POST` -- Adds a group to the given directory. For the XML specification, refer to the CROWD:group information resource.

Example of a search request for groups matching 'team' in directory 'atlassian crowd':

1
2
http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/group?search=team

Example of XML response to the above request:

1
2
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<groups>
 <group>
  <identifier>my-team</identifier> 
  <name>my-team</name> 
  <description>My Team</description> 
  <type>GROUP</type> 
 </group>
 <group>
  <identifier>team2</identifier> 
  <name>team2</name> 
  <description>Team 2</description>
  <type>GROUP</type>  
 </group>
 <group>
  <identifier>team3</identifier> 
  <name>team3</name> 
  <description>Team 3</description> 
  <type>GROUP</type> 
 </group>
 <group>
  <identifier>teamlead</identifier> 
  <name>teamlead</name> 
  <description>Team Leader</description> 
  <type>LEGACY_ROLE</type> 
 </group>
</groups>

Elements in the response:

Element	Description	Attributes
`groups`	A list of groups in the Crowd directory.
	Refer to the section on group information CROWD:below for the elements describing each group.

Example of JSON response for a list of groups:

1
2
{"groups":[
{"identifier":"my-team",
"name":"my-team",
"description":"My Team",
"type":"GROUP"},
{"identifier":"team2",
"name":"team2",
"description":"Team 2",
"type":"GROUP"},
{"identifier":"team3",
"name":"team3",
"description":"Team 3",
"type":"GROUP"},
{"identifier":"teamlead",
"name":"teamlead",
"description":"Team Leader"
"type":"LEGACY_ROLE"}]}

Group Information

URI	`/directory/DIRECTORY-KEY/group/GROUP-KEY` where `DIRECTORY-KEY` is the directory name and `GROUP-KEY` is the group name
Description	Retrieves or updates information about a specific group.
URI Parameters	None.
HTTP Methods	`GET` -- Returns information about the given group in the given directory. `DELETE` -- Deletes the given group from the given directory.

Here is an example of a request for information on group 'my-team' in directory 'atlassian crowd':

1
2
http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/group/my-team

The following cURL request deletes the group 'my-team', using basic authentication where the username and password are both 'admin':

1
2
curl -X DELETE http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/group/my-team -u admin:admin

Example of XML response for group information:

1
2
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<group>
  <identifier>my-team</identifier> 
  <name>my-team</name> 
  <description>My Team</description> 
  <type>GROUP</type> 
</group>

Elements in the response:

Element	Description
`group`	A group as defined in a Crowd directory.
`identifier`	The group name. Currently, this element contains the same value as the `name` element.
`name`	The group name.
`description`	A description of the group.
`type`	Indicates whether this item is a group or a role. Possible values are: `GROUP` -- The returned item is a group. `LEGACY_ROLE` -- The returned item is a role, as currently defined in Crowd.

Example of JSON response for group information:

1
2
{"identifier":"my-team",
"name":"my-team",
"description":"My Team",
"type":"GROUP"}

Group Membership for a User

URI	`/directory/DIRECTORY-KEY/user/USER-KEY/memberships` where `DIRECTORY-KEY` is the directory name and `USER-KEY` is the username
Description	Retrieves a list of the groups a given user belongs to, in the given directory.
URI Parameters	None.
HTTP Methods	`GET` -- Returns a list of groups that the user belongs to.

Here is an example of a request for the groups to which user 'adent' belongs, in directory 'atlassian crowd':

1
2
http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd/user/adent/memberships

Example of XML response for a list of group memberships:

1
2
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> 
<groups>
  <group>
   <identifier>my-team</identifier> 
   <name>my-team</name> 
   <description>My Team</description> 
   <type>GROUP</type> 
  </group>
  <group>
   <identifier>techwriter</identifier> 
   <name>techwriter</name> 
   <description>Technical writer</description> 
   <type>LEGACY_ROLE</type> 
  </group>
  <group>
   <identifier>confluence-users</identifier> 
   <name>confluence-users</name> 
   <description>Confluence users</description> 
   <type>GROUP</type> 
  </group>
</groups>

Elements in the response:

Element	Description
`groups`	A list of groups in the Crowd directory.
	Refer to the section on group information CROWD:above for the elements describing each group.

Example of JSON response for a list of group members:

1
2
{"group":
[{"identifier":"my-team",
"name":"my-team",
"description":"My Team",
"type":"GROUP"},
{"identifier":"techwriter",
"name":"techwriter",
"description":"Technical writer",
"type":"LEGACY_ROLE"},
{"identifier":"confluence-users",
"name":"confluence-users",
"description":"Confluence users",
"type":"GROUP"}]}

Overview of the Crowd REST APIs
Crowd Developer Documentation