Last updatedApr 4, 2019

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
http://host:port/context/rest/api-name/api-version/resource-name

Or without context:

1
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
http://localhost:8095/crowd/rest/admin/latest/directory/

Example of XML response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<?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
3
4
5
6
7
8
9
10
11
12
13
14
15
{"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
http://localhost:8095/crowd/rest/admin/latest/directory/atlassian%20crowd

Example of XML response:

1
2
3
4
5
6
<?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:

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
3
{"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

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

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

Example of XML response to the above request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 <?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
3
4
5
6
7
8
9
10
11
12
13
{"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
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
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
3
4
5
6
7
8
9
<?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
3
4
5
6
{"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
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
3
4
5
6
7
8
9
10
<?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

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

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

Example of XML response to the above request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{"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
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
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
3
4
5
6
7
<?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
3
4
{"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
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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<?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
3
4
5
6
7
8
9
10
11
12
13
{"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