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://docs.atlassian.com/atlassian-crowd/latest/REST/

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
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

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
3
4
5
6
7
8
9
10
11
12
13
14
15
<?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
3
4
5
6
<?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
3
4
5
6
7
8
9
10
11
<?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
3
4
5
6
<?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
3
4
<?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
3
4
5
6
7
8
9
<?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
3
4
5
6
<?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
3
4
5
6
7
8
9
10
11
12
13
<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
3
4
<?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
3
4
5
<?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
3
4
5
<?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
3
4
<?xml version="1.0" encoding="UTF-8"?>
<user name="username">
  ...
</user>

Unsuccessful Authentication Response

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

Request Body (XML):

1
2
3
4
<?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
3
4
5
6
7
8
9
<?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
3
4
5
6
7
8
<?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
3
4
5
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <reason>...</reason>
  <message>Error message</message>
</response>

Request Body (XML)

Description

1
2
3
4
5
6
7
8
9
10
11
<?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
3
4
5
6
7
<?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
3
4
5
6
<?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
3
4
5
6
7
8
9
10
11
12
13
<memberships>
 <membership group='parent-group'>
  <users>
   <user name='parent-group-user'/>
   ...
  </users>
  <groups>
   <group name='child-group'/>
   ...
  </groups>
 </membership>
 ...
</memberships>