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.

On this page:

Overview

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

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

Status Code

Response Body (XML)

GET /user?username=USERNAME

None.

Retrieves a user

200 (OK) if the user exists
404 (Not Found) if the user could not found

As in Figure 1

GET /user?username=USERNAME&expand=attributes

None.

Retrieves a user with attributes

200 (OK) if the user exists
404 (Not Found) if the user could not be found

As in Figure 1 with attributes filled in

POST /user

As in Figure 1, except with a password element

Creates a new user

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

(Since Crowd 2.8)

As in Figure 1 with attributes filled in.

PUT /user?username=USERNAME

As in Figure 1, except with a password element

Updates a user

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

As in Figure 1

DELETE /user?username=USERNAME

None.

Deletes a user

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

 

GET /user/attribute?username=USERNAME

None.

Retrieves a list of user attributes

200 (OK) if the user exists
404 (Not Found) if the user could not be found

A list of user attributes

POST /user/attribute?username=USERNAME

<?xml version="1.0" encoding="UTF-8"?>
<attributes>
  <attribute name="fruit">
    <values>
      <value>orange</value>
      <value>apple</value>
    </values>
  </attribute>
</attributes>

Stores all the user attributes for an existing user

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

 

DELETE /user/attribute?username=USERNAME&attributename=ATTRIBUTENAME

None.

Deletes a user attribute

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

 

PUT /user/password?username=USERNAME

<?xml version="1.0" encoding="UTF-8"?>
<password>
  <value>new-password</value>
</password>

Updates a user's password

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

 

POST /user/mail/password?username=USERNAME

None.

Sends the user a password reset link

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

 

POST  /user/mail/usernames?email=EMAIL

None.

Sends a username reminder to the users associated with the given email address

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

 

GET /user/group/direct?username=USERNAME

Optional start-index and max-results query params

None.

Retrieves the groups that the user is a direct member of

200 (OK) if the user is found, otherwise 404 (Not Found)

List of groups (See Group List figure)

GET /user/group/direct?username=USERNAME&groupname=GROUPNAME

None.

Retrieves the group that the user is a direct member of

200 (OK) if the user and group are found, otherwise 404 (Not Found)

See Group List figure

POST /user/group/direct?username=USERNAME

<?xml version="1.0" encoding="UTF-8"?>
<group name="groupname"/>

Adds the user (USERNAME) as a direct member of the group (GROUPNAME)

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

 

DELETE /user/group/direct?username=USERNAME&groupname=GROUPNAME

None

Removes the group membership of the user

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

 

GET /user/group/nested?username=USERNAME

Optional start-index and max-results query params

None

Retrieves the groups that the user is a nested member of

200 (OK) if the user is found, otherwise 404 (Not Found)

List of groups (See Group List figure)

GET /user/group/nested?username=USERNAME&groupname=GROUPNAME

None

Retrieves the group that the user is a nested member of

200 (OK) if the user and group are found, otherwise 404 (Not Found)

See Group List figure

Group Resource

<?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>
<?xml version="1.0" encoding="UTF-8"?>
<groups expand="group">
  <group name="groupname">
    <link rel="self" href="link_to_group"/>
  </group>
</groups>
<memberships>
 <membership group='parent-group'>
  <users>
   <user name='parent-group-user'/>
   ...
  </users>
  <groups>
   <group name='child-group'/>
   ...
  </groups>
 </membership>
 ...
</memberships>

Request Body (XML)

Description

Status Code

Response Body (XML)

GET /group?groupname=GROUPNAME

None.

Retrieves a group

200 (OK) if the group is found, otherwise 404 (Not Found)

As in Figure 2

GET /group?groupname=GROUPNAME&expand=attributes

None.

Retrieves a group with attributes

200 (OK) if the group is found, otherwise 404 (Not Found)

As in Figure 2 except including a list of group attributes

POST /group

As in Figure 2

Creates a new group

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

 

PUT /group?groupname=GROUPNAME

As in Figure 2

Updates a group

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

As in Figure 2

DELETE /group?groupname=GROUPNAME

None.

Deletes a group

204 (No Content) if the group is found and deleted
404 (Not Found) if the group could not be found

 

GET /group/attribute?groupname=GROUPNAME

None.

Retrieves a list of group attributes

200 (OK) if the group attribute is found, otherwise 404 (Not Found)

A list of group attributes

POST /group/attribute?groupname=GROUPNAME

None

Stores all the group attributes

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

 

DELETE /group/attribute?groupname=GROUPNAME&attributename=ATTRIBUTENAME

None

Deletes a group attribute

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

 

GET /group/user/direct?groupname=GROUPNAME

Optional start-index and max-results query params

Retrieves the users that are direct members of the specified group

200 (OK) if the group is found, otherwise 404 (Not Found)

List of users

POST /group/user/direct?groupname=GROUPNAME

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

Adds user as direct member of group

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

 

GET /group/user/direct?groupname=GROUPNAME&username=USERNAME

None

Retrieves the user that is a direct member of the specified group

200 (OK) if the group and user are found, otherwise 404 (Not Found)

See User figure

DELETE /group/user/direct?groupname=GROUPNAME&username=USERNAME

None

Removes the user membership

204 (No Content) if the user membership is successfully deleted
404 (Not Found) if the user or group could not be found

 

GET /group/user/nested?groupname=GROUPNAME

Optional start-index and max-results query params

None.

Retrieves the users that are nested members of the specified group

200 (OK) if the group is found, otherwise 404 (Not Found)

List of users

GET /group/user/nested?groupname=GROUPNAME&username=USERNAME

None.

Retrieves the user that is a nested member of the specified group

200 (OK) if the group and user are found, otherwise 404 (Not Found)

See User figure

GET /group/parent-group/direct?groupname=GROUPNAME

Optional start-index and max-results query params

None.

Retrieves the groups that are direct parents of the specified group

200 (OK) if the group is found, otherwise 404 (Not Found)

List of groups

POST /group/parent-group/direct?groupname=GROUPNAME

<?xml version="1.0" encoding="UTF-8"?>
<group name="parent-group-name"/>

Adds a direct parent group membership

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

 

GET /group/parent-group/direct?groupname=GROUPNAME&parent-groupname=PARENT-GROUPNAME

None.

Retrieves the group that is a direct parent of the specified group

200 (OK) if the groups are found, otherwise 404 (Not Found)

See Group List figure

GET /group/parent-group/nested?groupname=GROUPNAME

Optional start-index and max-results query params

None.

Retrieves the groups that are nested parents of the specified group

200 (OK) if the group is found, otherwise 404 (Not Found)

List of groups

GET /group/parent-group/nested?groupname=GROUPNAME&parent-groupname=PARENT-GROUPNAME

None

Retrieves the group that is a nested parent of the specified group

200 (OK) if the groups are found, otherwise 404 (Not Found)

See Group figure

GET /group/child-group/direct?groupname=GROUPNAME

Optional start-index and max-results query params

None

Retrieves the groups that are direct children of the specified group

200 (OK) if the group is found, otherwise 404 (Not Found)

List of groups (See Group List figure)

POST /group/child-group/direct?groupname=GROUPNAME

<?xml version="1.0" encoding="UTF-8"?>
<group name="child-group-name"/>

Adds a direct child group membership

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

 

GET /group/child-group/direct?groupname=GROUPNAME&child-groupname=CHILD-GROUPNAME

None.

Retrieves the group that is a direct child of the specified group

200 (OK) if the groups are found, otherwise 404 (Not Found)

See Membership figure

DELETE /group/child-group/direct?groupname=GROUPNAME&child-groupname=CHILD-GROUPNAME

None.

Deletes a child group membership

204 (No Content) if the child group membership is deleted
404 (Not Found) if the child or parent group could not be found

 

GET /group/child-group/nested?groupname=GROUPNAME

Optional start-index and max-results query params

None.

Retrieves the groups that are nested children of the specified group

200 (OK) if the group is found, otherwise 404 (Not Found)

List of groups (See Group List figure)

GET /group/child-group/nested?groupname=GROUPNAME&child-groupname=CHILD-GROUPNAME

None.

Retrieves the group that is a nested child of the specified group

200 (OK) if the groups are found, otherwise 404 (Not Found)

See Group figure

GET /group/membership

 Retrieves full details of all group memberships, with users and nested groups.200 (OK) on success, or 404 if unavailable in earlier releases of Crowd.

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.

<?xml version="1.0" encoding="UTF-8"?>
<user name="username">
  ...
</user>
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <reason>...</reason>
  <message>Error message</message>
</error>

POST /authentication?username=USERNAME

Request Body (XML)

Description

Status Code

Response Body (XML)

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

Authenticates a user

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

As below

Search Resource

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

Request Body (XML)

Description

Status

POST /search?entity-type=user

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

Searches for users (returning the usernames) with the specified search restriction

 

POST /search?entity-type=user&expand=user

As above

Searches for users with the specified search restriction

 

POST /search?entity-type=group

As above

Searches for groups (returning the group names) with the specified search restriction

 

POST /search?entity-type=group&expand=group

As above

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:

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

As above

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.

<?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>
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <reason>...</reason>
  <message>Error message</message>
</response>

Request Body (XML)

Description

Status

Response Body (XML)

POST /session

Optional validate-password and duration query params

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

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.

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

See Crowd SSO Session entity above

DELETE /session?username=USERNAME

Optional exclude query param
None.

Invalidate all tokens for a given user name.

Optionally, a token key can be saved from invalidation if specified in the exclude param

204 (No Content) if successful

404 (Not Found) if the user is not found

400 (Bad request) if the application is not found

 

GET /session/{token}

None.

Retrieves the token with the authenticated user expanded

200 (OK) if successfully retrieved
404 (Not Found) if the token is not found

See Crowd SSO Session entity above

POST /session/{token}

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

Validates the session token. Validating the token keeps the SSO session alive.

200 (OK) if successful
400 (Bad request) if the validation factors are incorrect
404 (Not Found) if the token cannot be found

See Crowd SSO Session entity above

DELETE /session/{token}

 

Invalidates the token

204 (No Content)

 

Cookie Configuration Resource

GET /config/cookie

Description

Status

Response Body (XML)

Retrieves cookie configurations

200 (OK)

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

Overview of the Crowd REST APIs
Crowd Developer Documentation

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