Crowd Server Developer

Crowd Server Developer

Rate this page:

Using the Crowd REST APIs


Crowd 2.1 and later.

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.

This page contains information on the factors common across all or most of the Crowd REST APIs. You can also read the details of the specific REST resources.

REST Resources and URI Structure

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


Or without context:


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.


With context:


Or without context:


Here is an explanation for each part of the URI:

  • host and port define the host and port where the Crowd application lives.
  • context is the servlet context of the Crowd installation. For example, the context might be crowd. Omit this section if your URI does not include a context.
  • rest denotes the REST API.
  • api-name identifies a specific Crowd API. In Crowd, the usermanagement API allows applications to interact with Crowd. (This is the path declared in the REST module type in the REST plugin descriptor.)
  • api-version is the API version number, e.g. 1 or 2. See the section on CROWD:API version control.
  • resource-name identifies the required resource. In some cases, this may be a generic resource name such as /foo. In other cases, this may include a generic resource name and key. For example, /foo returns a list of the foo items and /foo/{key} returns the full content of the foo identified by the given key.

Refer to the details of the specific REST resources.

URL Encoding

Query parameters will be the percent encoded representation of the UTF-8 bytes comprising the string.

Optional start-index and max-results Query Parameters

If a resource method offers an optional start-index and max-results query parameters, the default values are as follows (if not specified):

Query Parameter

Default Value





Media Types

The Crowd REST APIs return HTTP responses in one of the following formats:

Response Format

Requested via...


Requested via one of the following:

  • application/json in the HTTP Accept header
  • .json extension


Requested via one of the following:

  • application/xml in the HTTP Accept header
  • .xml extension

API Versions

The Crowd REST APIs are subject to version control. The version number of an API appears in its URI. For example, use this URI structure to request version 1 of the 'usermanagement' API:


To get the latest version of the API, you can also use the latest key-word. For example, if versions 1 and 2 of the 'usermanagement' API are available, the following two URIs will point to the same resources:

  • 1
  • 1


  • The API version number is an integer, such as 1 or 2.
  • The API version is independent of the Crowd release number.
  • The API version may, or may not, change with a new Crowd release. The API version number will change only when the updates to the API break the API contract, requiring changes in the code which uses the API. An addition to the API does not necessarily require a change to the API version number.
  • In the future, when there are multiple API versions available, it is the intention that each version of Crowd will support at least two API versions i.e. the latest API version and the previous API version.


Access to all resources (using any method) requires the client to be authenticated via basic authentication. See RFC 2617.

Your environment must retain cookies set by the Crowd server and retransmit them on subsequent calls, otherwise Crowd will have to re-authenticate the application on every REST call.

HTTP Response Codes and Error Responses

HTTP Response Code


200 (OK)

Returned when an application request is successful.

401 (Unauthorized)

Returned when the application name/password is invalid or if the application does not exist. Invalid user authentication details do not result in this status code.

403 (Forbidden)

Returned when an application is not allowed to make the request, such as when the application is inactive or the client's IP address is not in the list of known application addresses.

404 (Not Found)

Returned when the requested resource does not exist. For example, the user does not exist, the group does not exist, or the group membership does not exist.

All error responses except for 401 (Unauthorized) and 403 (Forbidden) return the following entity:

Unsuccessful Response

<?xml version="1.0" encoding="UTF-8"?>
  <message>Error message</message>




User does not have access to a particular application


Application does not have permission to perform the operation


User credentials have expired


Group is not found


REST method is given an illegal argument


User account is inactive


Username/password combination for authentication is invalid


The supplied credential is not valid. E.g. no password given when adding a user


Given email address is not valid


Given group is invalid. E.g. unknown group type, adding a group that already exists


Given SSO token is invalid


Given user is invalid. E.g. adding a user that already exists


When the child-parent relationship does not exist


Nested groups are not supported


Requested operation is not supported


User not found


Operation failed for any other reason


You will use the standard HTTP methods to access Crowd via the REST APIs. Please refer to the resource descriptions to see the HTTP methods available for each resource.

Crowd REST Resources
Overview of the Crowd REST APIs
Crowd Developer Documentation

Rate this page: