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

Last updated Dec 8, 2017

Crowd REST resources

Available:	Crowd 2.1 and later.
API version:	1

Note that these might be out of date. For the current versions of Crowd see https://developer.atlassian.com/server/crowd/rest/latest

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

Overview

Crowd offers a set of REST APIs for use by applications connecting to Crowd.

Please note the main difference between Crowd APIs and the APIs of other applications like JIRA and Confluence: In Crowd, an application is the client of Crowd, whereas in JIRA/Confluence a user is the client. For example, when authenticating a request to a Crowd REST resource via basic authentication, the application name and password is used (and not a username and password). Keep this in mind when using the REST APIs.

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

API Name - `usermanagement`

In Crowd 2.1, the only api-name available is usermanagement. This is the API that allows an application to interact with the Crowd server.

Examples

With context:

1
2
http://myhost.com:8095/crowd/rest/usermanagement/1/user?username=USERNAME
http://localhost:8095/crowd/rest/usermanagement/latest/user?username=USERNAME

Or without context:

1
2
http://crowd.myhost.com:8095/rest/usermanagement/1/user?username=USERNAME
http://crowd.myhost.com:8095/rest/usermanagement/latest/user?username=USERNAME

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, HTTP response codes, and so on.

User Resource

Figure 1: User

1
2
<?xml version="1.0" encoding="UTF-8"?>
  <user name="username" expand="attributes">
  <first-name>First</first-name>
  <last-name>Last</last-name>
  <display-name>First Last</display-name>
  <email>email@email.com</email>
  <active>true</active>
  <attributes>
    <link rel="self" href="link_to_user_attributes"/>
  </attributes>
  <password>
    <link rel="edit" href="link_to_user_password"/> <!-- /user/password?username=<username> -->
    <value>password</value> <!-- only used when creating a user, otherwise not filled in -->
  </password>
</user>

User List

1
2
<?xml version="1.0" encoding="UTF-8"?>
<users expand="user">
  <user name="username">
    <link rel="self" href="link_to_user"/>
  </user>
</users>

Request Body (XML)	Description
None.	GET `/user?username=USERNAME` Retrieves a user Status code: 200 (OK) if the user exists 404 (Not Found) if the user could not found Response Body (XML): As in Figure 1
None.	GET `/user?username=USERNAME&expand=attributes` Retrieves a user with attributes Status code: 200 (OK) if the user exists 404 (Not Found) if the user could not found Response Body (XML): As in Figure 1 with attributes filled in
As in Figure 1, except with a `password` element	POST `/user` Creates a new user Status code: 201 (Created) if the user is successfully created 400 (Bad Request) if the user password is left out or user already exists 403 (Forbidden) if the application is not allowed to create a new user Response Body (XML): (Since Crowd 2.8) As in Figure 1 with attributes filled in.
As in Figure 1, except with a `password` element	PUT `/user?username=USERNAME` Updates a user Status code: 204 (No Content) if the user previously existed and is now updated 400 (Bad Request) if the usernames in the request body and the URI do not match 403 (Forbidden) if the application is not allowed to update/create a user 404 (Not Found) if the user does not exist Response Body (XML): As in Figure 1
None.	DELETE `/user?username=USERNAME` Deletes a user Status code: 204 (No Content) if the user is found and deleted 403 (Forbidden) if the application is not allowed to delete the user 404 (Not Found) if the user could not be found
None.	GET `/user/attribute?username=USERNAME` Retrieves a list of user attributes Status code: 200 (OK) if the user exists 404 (Not Found) if the user could not be found Response Body (XML): A list of user attributes
1 2 `<?xml version="1.0" encoding="UTF-8"?> <attributes> <attribute name="fruit"> <values> <value>orange</value> <value>apple</value> </values> </attribute> </attributes>`	POST `/user/attribute?username=USERNAME` Stores all the user attributes for an existing user Status code: 204 (No Content) if the user attributes are successfully set 403 (Forbidden) if the application is not allowed to set user attributes 404 (Not Found) if the user could not be found
None.	DELETE `/user/attribute?username=USERNAME&attributename=ATTRIBUTENAME` Deletes a user attribute Status code: 204 (No Content) if the user attribute is successfully deleted or the attribute was not defined for the user 403 (Forbidden) if the application is not allowed to remove a user attribute 404 (Not Found) if the user could not be found
1 2 `<?xml version="1.0" encoding="UTF-8"?> <password> <value>new-password</value> </password>`	PUT `/user/password?username=USERNAME` Updates a user's password Status code: 204 (No Content) if the password is successfully updated 403 (Forbidden) if the application is not allowed to update a user's password 404 (Not Found) if the user could not be found
None.	POST `/user/mail/password?username=USERNAME` Sends the user a password reset link Status code: 204 (No Content) if the user is found 403 (Forbidden) if the application is not allowed to send the user a reset password link 404 (Not Found) if the user could not be found
None.	POST `/user/mail/usernames?email=EMAIL` Sends a username reminder to the users associated with the given email address Status code: 204 (No Content) if successful 403 (Forbidden) if the application is not allowed to send the user a username reminder 404 (Not Found) if the user could not be found
None.	GET `/user/group/direct?username=USERNAME` Optional `start-index` and `max-results` query params Retrieves the groups that the user is a direct member of Status code: 200 (OK) if the user is found, otherwise 404 (Not Found) Response Body (XML): List of groups (See Group List figure)
None.	GET `/user/group/direct?username=USERNAME&groupname=GROUPNAME` Retrieves the group that the user is a direct member of Status code: 200 (OK) if the user and group are found, otherwise 404 (Not Found) Response Body (XML): See Group List figure
1 2 `<?xml version="1.0" encoding="UTF-8"?> <group name="groupname"/>`	POST `/user/group/direct?username=USERNAME` Adds the user (`USERNAME`) as a direct member of the group (`GROUPNAME`) Status code: 201 (Created) if the user is successfully added to the group 400 (Bad Request) if the group could not be found 403 (Forbidden) if the application is not allowed to add the group membership 404 (Not Found) if the user cannot be found 409 (Conflict) if the user is already a direct member of the group
None	DELETE `/user/group/direct?username=USERNAME&groupname=GROUPNAME` Removes the group membership of the user Status code: 204 (No Content) if the group membership is successfully deleted 403 (Forbidden) if the application is not allowed to delete the group membership 404 (Not Found) if the user or group could not be found
None	GET `/user/group/nested?username=USERNAME` Optional `start-index` and `max-results` query params Retrieves the groups that the user is a nested member of Status code: 200 (OK) if the user is found, otherwise 404 (Not Found) Response Body (XML): List of groups (See Group List figure)
None	GET `/user/group/nested?username=USERNAME&groupname=GROUPNAME` Retrieves the group that the user is a nested member of Status code: 200 (OK) if the user and group are found, otherwise 404 (Not Found) Response Body (XML): See Group List figure

Group Resource

Figure 2: Group

1
2
<?xml version="1.0" encoding="UTF-8"?>
<group name="groupname" expand="attributes">
  <type>GROUP</type>
  <description>Group Description</description>
  <active>true</active>
  <attributes>
    <link rel="self" href="link_to_group_attributes"/>
  </attributes>
</group>

Group List

1
2
<?xml version="1.0" encoding="UTF-8"?>
<groups expand="group">
  <group name="groupname">
    <link rel="self" href="link_to_group"/>
  </group>
</groups>

All Group Memberships

1
2
<memberships>
 <membership group='parent-group'>
  <users>
   <user name='parent-group-user'/>
   ...
  </users>
  <groups>
   <group name='child-group'/>
   ...
  </groups>
 </membership>
 ...
</memberships>

Request Body (XML)	Description
None.	GET `/group?groupname=GROUPNAME` Retrieves a group Status Code: 200 (OK) if the group is found, otherwise 404 (Not Found) Response Body (XML): As in Figure 2
None.	GET `/group?groupname=GROUPNAME&expand=attributes` Retrieves a group with attributes Status Code: 200 (OK) if the group is found, otherwise 404 (Not Found) Response Body (XML): As in Figure 2 except including a list of group attributes
As in Figure 2	POST `/group` Creates a new group Status Code: 201 (Created) if the group is successfully created 400 (Bad Request) if the group already exists 403 (Forbidden) if the application is not allowed to create a new group
As in Figure 2	PUT `/group?groupname=GROUPNAME` Updates a group Status Code: 200 (OK) if the group previously existed and is now updated 400 (Bad Request) if the groupname in the request body and the URI do not match 403 (Forbidden) if the application is not allowed to update/create a group 404 (Not Found) if the group does not exist Response Body (XML): As in Figure 2
None.	DELETE `/group?groupname=GROUPNAME` Deletes a group Status Code: 204 (No Content) if the group is found and deleted 404 (Not Found) if the group could not be found
None.	GET `/group/attribute?groupname=GROUPNAME` Retrieves a list of group attributes Status Code: 200 (OK) if the group attribute is found, otherwise 404 (Not Found) Response Body (XML): A list of group attributes
None	POST `/group/attribute?groupname=GROUPNAME` Stores all the group attributes Status Code: 204 (No Content) if the group attributes are successfully set 403 (Forbidden) if the application is not allowed to set group attributes 404 (Not Found) if the group could not be found
None	DELETE `/group/attribute?groupname=GROUPNAME&attributename=ATTRIBUTENAME` Deletes a group attribute Status Code: 204 (No Content) if the group attribute is successfully deleted 403 (Forbidden) if the application is not allowed to remove a group attribute 404 (Not Found) if the group or attribute could not be found
Optional `start-index` and `max-results` query params	GET `/group/user/direct?groupname=GROUPNAME` Retrieves the users that are direct members of the specified group Status Code: 200 (OK) if the group is found, otherwise 404 (Not Found) Response Body (XML): List of users
1 2 `<?xml version="1.0" encoding="UTF-8"?> <user name="username"/>`	POST `/group/user/direct?groupname=GROUPNAME` Adds user as direct member of group Status Code: 201 (Created) if the user is successfully added as a member of the group 400 (Bad Request) if the user could not be found 404 (Not Found) if the group could not be found 409 (Conflict) if the user is already a direct member of the group
None	GET `/group/user/direct?groupname=GROUPNAME&username=USERNAME` Retrieves the user that is a direct member of the specified group Status Code: 200 (OK) if the group and user are found, otherwise 404 (Not Found) Response Body (XML): See User figure
None	DELETE `/group/user/direct?groupname=GROUPNAME&username=USERNAME` Removes the user membership Status Code: 204 (No Content) if the user membership is successfully deleted 404 (Not Found) if the user or group could not be found
None.	GET `/group/user/nested?groupname=GROUPNAME` Optional `start-index` and `max-results` query params Retrieves the users that are nested members of the specified group Status Code: 200 (OK) if the group is found, otherwise 404 (Not Found) Response Body (XML): List of users
None.	GET `/group/user/nested?groupname=GROUPNAME&username=USERNAME` Retrieves the user that is a nested member of the specified group Status Code: 200 (OK) if the group and user are found, otherwise 404 (Not Found) Response Body (XML): See User figure
None.	GET `/group/parent-group/direct?groupname=GROUPNAME` Optional start-index and max-results query params Retrieves the groups that are direct parents of the specified group Status Code: 200 (OK) if the group is found, otherwise 404 (Not Found) Response Body (XML): List of groups
1 2 `<?xml version="1.0" encoding="UTF-8"?> <group name="parent-group-name"/>`	POST `/group/parent-group/direct?groupname=GROUPNAME` Adds a direct parent group membership Status Code: 201 (Created) if the parent group membership is successfully added 400 (Bad Request) if the parent group could not be found, or adding the membership would result in a circular dependency 404 (Not Found) if the group could not be found
None.	GET `/group/parent-group/direct?groupname=GROUPNAME&parent-groupname=PARENT-GROUPNAME` Retrieves the group that is a direct parent of the specified group Status Code: 200 (OK) if the groups are found, otherwise 404 (Not Found) Response Body (XML): See Group List figure
None.	GET `/group/parent-group/nested?groupname=GROUPNAME` Optional `start-index` and `max-results` query params Retrieves the groups that are nested parents of the specified group Status Code: 200 (OK) if the group is found, otherwise 404 (Not Found) Response Body (XML): List of groups
None	GET `/group/parent-group/nested?groupname=GROUPNAME&parent-groupname=PARENT-GROUPNAME` Retrieves the group that is a nested parent of the specified group Status Code: 200 (OK) if the groups are found, otherwise 404 (Not Found) Response Body (XML): See Group figure
None	GET `/group/child-group/direct?groupname=GROUPNAME` Optional `start-index` and `max-results` query params Retrieves the groups that are direct children of the specified group Status Code: 200 (OK) if the group is found, otherwise 404 (Not Found) Response Body (XML): List of groups (See Group List figure)
1 2 `<?xml version="1.0" encoding="UTF-8"?> <group name="child-group-name"/>`	POST /`group/child-group/direct?groupname=GROUPNAME` Adds a direct child group membership Status Code: 201 (Created) if the child group membership is successfully added 400 (Bad Request) if the child group could not be found, or adding the membership would result in a circular dependency 404 (Not Found) if the group could not be found
None.	GET `/group/child-group/direct?groupname=GROUPNAME&child-groupname=CHILD-GROUPNAME` Retrieves the group that is a direct child of the specified group Status Code: 200 (OK) if the groups are found, otherwise 404 (Not Found) Response Body (XML): See Membership figure
None.	DELETE `/group/child-group/direct?groupname=GROUPNAME&child-groupname=CHILD-GROUPNAME` Deletes a child group membership Status Code: 204 (No Content) if the child group membership is deleted 404 (Not Found) if the child or parent group could not be found
None.	GET `/group/child-group/nested?groupname=GROUPNAME` Optional `start-index` and `max-results` query params Retrieves the groups that are nested children of the specified group Status Code: 200 (OK) if the group is found, otherwise 404 (Not Found) Response Body (XML): List of groups (See Group List figure)
None.	GET `/group/child-group/nested?groupname=GROUPNAME&child-groupname=CHILD-GROUPNAME` Retrieves the group that is a nested child of the specified group Status Code: 200 (OK) if the groups are found, otherwise 404 (Not Found) Response Body (XML): See Group figure
	GET `/group/membership` Retrieves full details of all group memberships, with users and nested groups. Status Code: 200 (OK) on success, or 404 if unavailable in earlier releases of Crowd. Response Body (XML): Membership details for every group. See All Group Memberships figure. This resource is optimised for streaming XML responses, and does not support JSON responses.

User Authentication Resource

No session is created in user authentication. An application can simply ask Crowd "is this username/password valid?" This is the primary purpose of the Authentication resource.

Successful Authentication Response

1
2
<?xml version="1.0" encoding="UTF-8"?>
<user name="username">
  ...
</user>

Unsuccessful Authentication Response

1
2
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <reason>...</reason>
  <message>Error message</message>
</error>

Request Body (XML):

1
2
<?xml version="1.0" encoding="UTF-8"?>
<password>
  <value>Password</value>
</password>

Description:

POST /authentication?username=USERNAME

Authenticates a user

Status Code:

200 (OK) if successful 400 (Bad Request) if unsuccessful

Response Body (XML):

As below

Search Resource

All Search resource methods have optional start-index and max-results query params.

Request Body (XML)	Description
1 2 `<?xml version="1.0" encoding="UTF-8"?> <property-search-restriction> <property> <name>email</name> <type>STRING</type> </property> <match-mode>EXACTLY_MATCHES</match-mode> <value>bob@example.net</value> </property-search-restriction>`	POST `/search?entity-type=user` Searches for users (returning the usernames) with the specified search restriction
As above	POST `/search?entity-type=user&expand=user` Searches for users with the specified search restriction
As above	POST `/search?entity-type=group` Searches for groups (returning the group names) with the specified search restriction
As above	POST `/search?entity-type=group&expand=group` Searches for groups with the specified search restriction

From Crowd 2.2 onwards, you can perform searches using the Crowd Query Language. Use a GET, rather than a POST, and provide the restriction parameter with CQL:

Request Body (XML):

As above

Descrition:

GET /search?entity-type=ENTITY_TYPE&restriction=CQL_QUERY

Searches for entities of ENTITY_TYPE (either 'user' or 'group') with the specified search restriction (as Crowd Query Language).

Crowd SSO Token Resource

The Crowd SSO token resource allows an application to authenticate a user and receive an SSO token from the Crowd server. The application decides what to do with the SSO token, though normally this SSO token is set as a cookie in the user's browser.

Crowd SSO Session

1
2
<?xml version="1.0" encoding="UTF-8"?>
<session expand="user">
  <link rel="self" href="link_to_token_URI"/>
  <token>abc123</token>
  <user name="username"/> <!-- authenticated user -->
  <created-date>2013-01-30T16:38:27.369+11:00</created-date>
  <expiry-date>2013-01-30T17:08:27.369+11:00</expiry-date>
</session>

Unsuccessful Crowd SSO Session Creation Response

1
2
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <reason>...</reason>
  <message>Error message</message>
</response>

Request Body (XML)	Description
1 2 `<?xml version="1.0" encoding="UTF-8"?> <authentication-context> <username>my_username</username> <password>my_password</password> <validation-factors> <validation-factor> <name>remote_address</name> <value>127.0.0.1</value> </validation-factor> </validation-factors> </authentication-context>`	POST `/session` Optional `validate-password` and `duration` query params Create new session token valid for `duration` seconds, or for the server default session timeout if no `duration` is specified or if `duration` is longer than the server default session timeout Either user password needs to be valid or `validate-password` query param must be set to `false` If an ongoing session already exists for the same authentication credentials and validation factors, then that session token is returned. Status: 201 (Created) with successful response as above if the session creation was successful or an ongoing session already existed 400 (Bad Request) with unsuccessful response as above if the user authentication details are incorrect (e.g., bad password, inactive user, user does not have permission to authenticate with the application). Response Body (XML): See Crowd SSO Session entity above
None.	DELETE `/session?username=USERNAME` Optional `exclude` query param Invalidate all tokens for a given user name. Optionally, a token key can be saved from invalidation if specified in the `exclude` param Status: 204 (No Content) if successful 404 (Not Found) if the user is not found 400 (Bad request) if the application is not found
None.	GET `/session/{token`} Retrieves the token with the authenticated user expanded Status: 200 (OK) if successfully retrieved 404 (Not Found) if the token is not found Response Body (XML): See Crowd SSO Session entity above
1 2 `<?xml version="1.0" encoding="UTF-8"?> <validation-factors> <validation-factor> <name>remote_address</name> <value>127.0.0.1</value> </validation-factor> </validation-factors>`	POST `/session/{token`} Validates the session token. Validating the token keeps the SSO session alive. Status: 200 (OK) if successful 400 (Bad request) if the validation factors are incorrect 404 (Not Found) if the token cannot be found Response Body (XML): See Crowd SSO Session entity above
	DELETE `/session/{token`} Invalidates the token Status: 204 (No Content)

GET /config/cookie - Retrieves cookie configurations.

Status: 200 (OK)

Response Body (XML):

1
2
<?xml version="1.0" encoding="UTF-8"?>
<cookie-config>
  <domain>.atlassian.com</domain>
  <secure>true</secure>
  <name>cookie-name</name>
</cookie-config>

Overview of the Crowd REST APIs Crowd Developer Documentation

1
2
<memberships>
 <membership group='parent-group'>
  <users>
   <user name='parent-group-user'/>
   ...
  </users>
  <groups>
   <group name='child-group'/>
   ...
  </groups>
 </membership>
 ...
</memberships>