Crowd REST API Reference
Crowd 2.12.0
Welcome to the Crowd REST API reference. This page documents the REST resources available in Crowd, along with expected HTTP response codes and sample requests. This set of REST APIs is intended to be used by applications connecting to Crowd.
URI Structure
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). Below are details of the resources made available by the APIs. To use a REST API, your application will make an HTTP request and parse the response.
Depending on the resource, responses are returned as JSON and/or XML. For resources that offer both, you can use the Accept HTTP header to specify which one you prefer. URIs for Crowd's REST API resource have the following structure:
http://host:port/context/rest/api-name/api-version/resource-name
Currently the following API names are available, which will be discussed further below:
usermanagement
- intended for applications to interact with the Crowd server for user management operationsadmin
- intended to be used for administrative operations on the Crowd server
Each API has it's version. However, there is also a symbolic version, called latest
,
which resolves to the latest version supported by the given Crowd instance.
As an example, if you wanted to retrieve information about a user 'admin' from a Crowd instance, you would access:
https://crowd-server:8095/crowd/rest/usermanagement/latest/user?username=admin
There is a WADL document that contains the documentation for each resource in the REST API. It is available here.
Authentication
The preferred authentication methods for the Crowd REST APIs is HTTP basic authentication (when using SSL).
Please note that the usermanagement
resource expects the callers to authenticate using the application
credentials (i.e. the application name and password configured in Crowd). Calls to this APIs are restricted by IP
as configured. Permissions and seen users, groups and other entities depend on the application configuration as well.
Other resources expect the callers to authenticate using the user credentials. Permissions depend on configured user permissions.
Expansion
In order to simplify API responses, the Crowd REST API uses resource expansion. This means the API will only return parts of the resource when explicitly requested.
You can use the expand
query parameter to specify a comma-separated list of entities that you want
expanded, identifying each of them by name. For example, appending ?expand=attributes
to a users's
URI requests the inclusion of the user attribute names and values in the response.
Continuing with our example above, we would use the following URL to get the attribute values for the 'admin' user:
https://crowd-server:8095/crowd/rest/usermanagement/latest/user?username=admin&expand=attributes
To discover the identifiers for each entity, look at the expand
property in the parent object. In the
JSON example below, the resource declares widgets as being expandable.
{"expand":"widgets", "widgets":{"widgets":[]}}
You can use the dot notation to specify expansion of entities within another entity. For example
?expand=widgets.fringels
would expand the widgets collection and also the fringel property on each
widget.
Experimental methods
Methods marked as experimental may change without an earlier notice. We are looking for your feedback for these methods.
Resources
admin/1.0/auditlog
Add changesetPOST /rest/admin/1.0/auditlog
Stores a changeset in the audit log
Request
Example
{"id":1,"timestamp":"2017-04-26T00:00:00.000+0200","authorType":"USER","authorId":1,"authorName":"admin","eventType":"MODIFIED","entityType":"APPLICATION","entityId":1,"entityName":"JIRA 7.4","ipAddress":"127.0.0.1","eventMessage":"Application modified","entries":[{"propertyName":"name","oldValue":"JIRA 7.3","newValue":"JIRA 7.4"}]}
Responses
- Status
201Returned when given changeset was stored in audit log
Get configurationGET /rest/admin/1.0/auditlog/configuration
Retrieves current audit log configuration
Responses
- Status
200Returned if configuration was successfully retrieved
Example
{"retentionPeriod":"UNLIMITED"}
Set configurationPUT /rest/admin/1.0/auditlog/configuration
Saves new audit log configuration
Request
Example
{"retentionPeriod":"UNLIMITED"}
Responses
- Status
200Returned if configuration was successfully saved
Example
{"retentionPeriod":"UNLIMITED"}
Search audit logPOST /rest/admin/1.0/auditlog/search
Searches audit log for entries matching given restrictions
Request
query parameters
parameter | type | description |
---|---|---|
max-results | int Default: 1000 | maximum number of results returned |
start-index | int Default: 0 | starting index of the results |
Example
{"restriction-type":"property-search-restriction","property":{"name":"author","type":"STRING"},"value":"admin","match-mode":"EXACTLY_MATCHES"}
Responses
- Status
200Returned when restriction was valid
Example
{"changesets":[{"id":1,"timestamp":"2017-04-26T00:00:00.000+0200","authorType":"USER","authorId":1,"authorName":"admin","eventType":"MODIFIED","entityType":"APPLICATION","entityId":1,"entityName":"JIRA 7.4","ipAddress":"127.0.0.1","eventMessage":"Application modified","entries":[{"propertyName":"name","oldValue":"JIRA 7.3","newValue":"JIRA 7.4"}]}]}
usermanagement/1/authentication
User Authentication Resource.
Authenticate userPOST /rest/usermanagement/1/authentication
Authenticates a user. Does not generate an SSO token. For SSO please take a look at the SSO token resource.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user |
Example
{"value":"hunter2"}
Responses
- Status
200Returned if successful
Example
{"expand":"attributes","link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user?username=sampleuser","rel":"self"},"name":"sampleuser","password":{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/password?username=sampleuser","rel":"edit"}},"key":"557057:927441f1-cc92-4030-b633-8a2bbdf7136e","active":true,"attributes":{"attributes":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts","rel":"self"},"name":"invalidPasswordAttempts","values":["0"]},{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"},"name":"requiresPasswordChange","values":["false"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"}},"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"}
- Status
400Returned if unsuccessful
usermanagement/1/config/cookie
Get configGET /rest/usermanagement/1/config/cookie
Returns the Cookie configuration information.
Responses
- Status
200Returned if successful
Example
{"domain":".atlassian.com","secure":true,"name":"cookie-name"}
usermanagement/1/group
Get groupGET /rest/usermanagement/1/group
Retrieves a group.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | Name of the group to retrieve. |
Responses
- Status
200Returned if the group was found.
Example
{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}}
- Status
404Returned if the group was not found.
Add groupPOST /rest/usermanagement/1/group
Adds a new group.
Request
Example
{"name":"newgroupname","description":"description","type":"GROUP"}
Responses
- Status
201Returned if the group is successfully created.
Example
{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}}
- Status
400Returned if the group already exists.
- Status
403Returned if the application is not allowed to create a new group.
Remove groupDELETE /rest/usermanagement/1/group
Deletes a group.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | Name of the group to delete. |
Responses
- Status
204Returned if the group was found and deleted.
- Status
404Returned if the group could not be found.
Update groupPUT /rest/usermanagement/1/group
Updates an existing group.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | the name of the group to update. |
Example
{"name":"newgroupname","description":"description","type":"GROUP"}
Responses
- Status
200Returned if the group previously existed and is now updated.
Example
{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}}
- Status
400Returned if the groupname in the request body and the URI do not match.
- Status
403Returned if the application is not allowed to update/create a group.
- Status
404Returned if the group does not exist.
Get group attributesGET /rest/usermanagement/1/group/attribute
Retrieves a list of group attributes.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | Name of the group to fetch attributes from. |
Responses
- Status
200Returned if the group attribute was found.
Example
{"attributes":[{"link":{"href":"https://crowdserver/crowd","rel":"self"},"name":"attribute","values":["value1","value2"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?username=sampleuser","rel":"self"}}
- Status
404Returned if the group attribute could not be found.
Store group attributesPOST /rest/usermanagement/1/group/attribute
Stores the group attributes.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | name of the group. |
Example
{"attributes":[{"link":{"href":"https://crowdserver/crowd","rel":"self"},"name":"attribute","values":["value1","value2"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?username=sampleuser","rel":"self"}}
Responses
- Status
204Returned if the group attributes are successfully set.
- Status
403Returned if the application is not allowed to set group attributes.
- Status
404Returned if the group attribute could not be found.
Delete group attributeDELETE /rest/usermanagement/1/group/attribute
Deletes a group attribute.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | name of the group. |
attributename | string | name of the attribute to delete. |
Responses
- Status
204Returned if the group attribute is successfully deleted.
- Status
403Returned if the application is not allowed to remove a group attribute.
- Status
404Returned if the group or attribute could not be found.
Get direct children of groupGET /rest/usermanagement/1/group/child-group/direct
Retrieves the groups that are direct children of the specified group or a single direct child of that group with the specified name.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | Name of the parent group which will have its children fetched. |
child-groupname | string | If specified then only the direct child group with this name will be returned. |
start-index | int Default: 0 | start index if using paged queries, only applicable when |
max-results | int Default: 1000 | maximum amount of results to return, only applicable when |
Responses
- Status
200Returned if the group was found.
Example
{"expand":"group","groups":[{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}},{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}}]}
- Status
404Returned if the group could not be found.
Add direct child group membershipPOST /rest/usermanagement/1/group/child-group/direct
Adds a direct child group membership.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | Name of the parent group to which the direct child group will be added. |
Example
{"name":"groupname"}
Responses
- Status
201Returned if the child group membership is successfully added.
Example
"https://crowdserver/crowd/group/user/direct?groupname=group&username=user"
- Status
400Returned if the child group could not be found, or adding the membership would result in a circular dependency.
- Status
404Returned if the group could not be found.
Remove direct child group membershipDELETE /rest/usermanagement/1/group/child-group/direct
Deletes a child group membership.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | Name of the parent group. |
child-groupname | string | Name of the child group. |
Responses
- Status
204Returned if the child group membership is deleted.
- Status
404Returned if the child or parent group could not be found.
Get nested children of groupGET /rest/usermanagement/1/group/child-group/nested
Retrieves nested children of the specified group or a single nested child of that group with the specified name.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | Name of the parent group which will have its nested children fetched. |
child-groupname | string | If provided then only a single nested child group with this name will be fetched from the group specified by |
start-index | int Default: 0 | start index if using paged queries, only applicable when |
max-results | int Default: 1000 | maximum amount of results to return, only applicable when |
Responses
- Status
200Returned if the groups were found.
Example
{"expand":"group","groups":[{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}},{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}}]}
- Status
404Returned if the groups could not be found.
Get all membershipsGET /rest/usermanagement/1/group/membership
Retrieves full details of all group memberships, with users and nested groups. This resource is optimised for streaming XML responses, and does not support JSON responses.
Responses
- Status
200Returned on success.
- Status
404Returned if unavailable in earlier releases of Crowd.
Get direct parents of groupGET /rest/usermanagement/1/group/parent-group/direct
Retrieves the groups that are direct parents of the specified group or a direct parent group of the specified child group.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | if |
child-groupname | string | if specified this will return a single direct parent group of this group with the name |
start-index | int Default: 0 | start index if using paged queries, only applicable when |
max-results | int Default: 1000 | maximum amount of results to return, only applicable when |
Responses
- Status
200Returned if the group is found.
Example
{"expand":"group","groups":[{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}},{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}}]}
- Status
404Returned if the group could not be found.
Add direct parent group membershipPOST /rest/usermanagement/1/group/parent-group/direct
Adds a direct parent group membership.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | name of the child group. |
Responses
- Status
201Returned if the parent group membership is successfully added.
Example
"https://crowdserver/crowd/group/user/direct?groupname=group&username=user"
- Status
400Returned if the parent group could not be found, or adding the membership would result in a circular dependency.
- Status
404Returned if the group could not be found.
Get nested parent groupsGET /rest/usermanagement/1/group/parent-group/nested
Retrieves the groups that are nested parents of the specified group or a single nested parent of that group with the specified name.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | name of the group of which the nested parents will be returned. |
parent-groupname | string | if specified then the single nested parent group with this name of the group specified by |
start-index | int Default: 0 | start index if using paged queries, only applicable when |
max-results | int Default: 1000 | maximum amount of results to return, only applicable when |
Responses
- Status
200Returned if the group was found.
Example
{"expand":"group","groups":[{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}},{"expand":"attributes","link":{"href":"link_to_group","rel":"self"},"name":"groupname","description":"Group Description","type":"GROUP","active":true,"attributes":{"attributes":[],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/group/attributes?groupname=groupname","rel":"self"}}}]}
- Status
404Returned if the group could not be found.
Get direct members of groupGET /rest/usermanagement/1/group/user/direct
Retrieves the users that are direct members of the specified group or a specified user who is a direct member of that group.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | name of the group. |
username | string | if specified it will return a single user if the user is a direct member of the specified group. |
start-index | int Default: 0 | start index if using paged queries, only applicable when |
max-results | int Default: 1000 | maximum amount of results to return, only applicable when |
Responses
- Status
200Returned if the group is found.
Example
{"expand":"user","users":[{"expand":"attributes","link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user?username=sampleuser","rel":"self"},"name":"sampleuser","password":{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/password?username=sampleuser","rel":"edit"}},"key":"557057:927441f1-cc92-4030-b633-8a2bbdf7136e","active":true,"attributes":{"attributes":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts","rel":"self"},"name":"invalidPasswordAttempts","values":["0"]},{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"},"name":"requiresPasswordChange","values":["false"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"}},"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"},{"expand":"attributes","link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user?username=sampleuser","rel":"self"},"name":"sampleuser","password":{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/password?username=sampleuser","rel":"edit"}},"key":"557057:927441f1-cc92-4030-b633-8a2bbdf7136e","active":true,"attributes":{"attributes":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts","rel":"self"},"name":"invalidPasswordAttempts","values":["0"]},{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"},"name":"requiresPasswordChange","values":["false"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"}},"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"}]}
- Status
404Returned if the group could not be found or the specified user is not a direct member of the group.
Add user as direct group memberPOST /rest/usermanagement/1/group/user/direct
Adds a user as a direct member of the specified group.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | name of the group to which the user will be added. |
Example
{"name":"sampleuser"}
Responses
- Status
201Returned if the user is successfully added as a member of the group.
Example
"https://crowdserver/crowd/group/user/direct?groupname=group&username=user"
- Status
400Returned if the user could not be found.
- Status
404Returned if the group could not be found.
- Status
409Returned if the user is already a direct member of the group.
Remove direct group membershipDELETE /rest/usermanagement/1/group/user/direct
Removes the user membership.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | name of the group from which the user membership will be removed. |
username | string | name the user to have their membership removed. |
Responses
- Status
204Returned if the user membership is successfully deleted.
- Status
404Returned if the user or group could not be found.
Get nested members of groupGET /rest/usermanagement/1/group/user/nested
Retrieves the users that are nested members of the specified group or a single user who is a nested member of the specified group.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | name of the group. |
username | string | if specified it will return a single user if the user is a nested member of the specified group. |
start-index | int Default: 0 | start index if using paged queries, only applicable |
max-results | int Default: 1000 | maximum amount of results to return, only applicable when |
Responses
- Status
200Returned if the group is found.
Example
{"expand":"user","users":[{"expand":"attributes","link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user?username=sampleuser","rel":"self"},"name":"sampleuser","password":{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/password?username=sampleuser","rel":"edit"}},"key":"557057:927441f1-cc92-4030-b633-8a2bbdf7136e","active":true,"attributes":{"attributes":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts","rel":"self"},"name":"invalidPasswordAttempts","values":["0"]},{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"},"name":"requiresPasswordChange","values":["false"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"}},"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"},{"expand":"attributes","link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user?username=sampleuser","rel":"self"},"name":"sampleuser","password":{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/password?username=sampleuser","rel":"edit"}},"key":"557057:927441f1-cc92-4030-b633-8a2bbdf7136e","active":true,"attributes":{"attributes":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts","rel":"self"},"name":"invalidPasswordAttempts","values":["0"]},{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"},"name":"requiresPasswordChange","values":["false"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"}},"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"}]}
- Status
404Returned if the user or group could not be found or the specified user is not a nested member of the group.
usermanagement/1/search
Search resource.
SearchPOST /rest/usermanagement/1/search
Searches for entities of entity-type (either 'user' or 'group') satisfying the given search restriction.
Request
query parameters
parameter | type | description |
---|---|---|
entity-type | string | type of the entity to search |
max-results | int Default: 1000 | maximum number of results returned |
start-index | int Default: 0 | starting index of the results |
Example
{"restriction-type":"property-search-restriction","property":{"name":"email","type":"STRING"},"value":"bob@example.net","match-mode":"EXACTLY_MATCHES"}
Responses
- Status
200list of users or groups
Example
{"expand":"group","groups":[{"link":{"href":"https://crowdserver/crowd/group?groupname=group&groupname=crowd-administrators","rel":"self"},"name":"crowd-administrators"}]}
- Status
409when the entity type is not specified or uknown
Search by cqlGET /rest/usermanagement/1/search
Searches for entities of entity-type (either 'user' or 'group') with the specified search restriction (as Crowd Query Language).
Request
query parameters
parameter | type | description |
---|---|---|
entity-type | string | type of the entity to search |
max-results | int Default: 1000 | maximum number of results returned |
start-index | int Default: 0 | starting index of the results |
restriction | string Default: | restriction entities must satisfy in the Crowd Query Language |
Responses
- Status
200list of users or groups
Example
{"expand":"user","users":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user?username=sampleuser","rel":"self"},"name":"sampleuser"}]}
- Status
409when the entity type is not specified or uknown
usermanagement/1/session
Crowd SSO Token Resource.
Delete tokens for userDELETE /rest/usermanagement/1/session
Invalidate all tokens for a given user name.
Optionally, a token key can be saved from invalidation if specified in the exclude
param
Request
query parameters
parameter | type | description |
---|---|---|
username | string | The user for which the tokens will be invalidated |
exclude | string | The token to exclude |
Responses
- Status
400Returned if the application is not found
- Status
204Returned if successful
- Status
404Returned if the user is not found
Authenticate userPOST /rest/usermanagement/1/session
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 the user password needs to be valid or the 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.
Request
query parameters
parameter | type | description |
---|---|---|
validate-password | boolean Default: true | true if the password should be validated (optional, defaults to true) |
duration | long Default: -1 | requested duration of the token, in seconds (optional, defaults to server session duration) |
Example
{"username":"my_username","password":"my_password","validation-factors":{"validationFactors":[{"name":"remote_address","value":"127.0.0.1"}]}}
Responses
- Status
201Returned the session creation was successful or an ongoing session already existed. Contains the Crowd SSO token.
Example
{"expand":"user","token":"abc123","user":{"name":"sampleuser"},"link":{"href":"https://crowdserver/crowd/session/abcc123","rel":"self"},"created-date":1464445800000,"expiry-date":1464449400000}
- Status
400Returned if the user authentication details are incorrect (e.g., bad password, inactive user, user does not have permission to authenticate with the application).
Get sessionGET /rest/usermanagement/1/session/{token}
Retrieves the token with the authenticated user expanded.
Responses
- Status
200Returned if successfully retrieved
Example
{"expand":"user","token":"abc123","user":{"name":"sampleuser"},"link":{"href":"https://crowdserver/crowd/session/abcc123","rel":"self"},"created-date":1464445800000,"expiry-date":1464449400000}
- Status
404Returned if the token is not found
Invalidate tokenDELETE /rest/usermanagement/1/session/{token}
Invalidates the Crowd SSO token.
Responses
- Status
204Returned if successful
Validate tokenPOST /rest/usermanagement/1/session/{token}
Validates the session token. Validating the token keeps the SSO session alive.
Request
Example
{"validationFactors":[{"name":"remote_address","value":"127.0.0.1"}]}
Responses
- Status
200Returned if successful
Example
{"expand":"user","token":"abc123","user":{"name":"sampleuser"},"link":{"href":"https://crowdserver/crowd/session/abcc123","rel":"self"},"created-date":1464445800000,"expiry-date":1464449400000}
- Status
400Returned if the validation factors are incorrect
- Status
404Returned if if the token cannot be found
usermanagement/1/user
Update userPUT /rest/usermanagement/1/user
Updates a user.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user to update |
Example
{"name":"sampleuser","password":{"value":"secret"},"active":true,"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"}
Responses
- Status
400invalid user data, for example the usernames in the body and the uri don't match
- Status
204the user was successfully updated
- Status
403the application is not allowed to update a user
- Status
404the user doesn't exist
Remove userDELETE /rest/usermanagement/1/user
Removes a user.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user to remove |
Responses
- Status
204the user was successfully removed
- Status
403the application is not allowed to remove the user
- Status
404the user could not be found
Get userGET /rest/usermanagement/1/user
Retrieves the user details. Either username or key query parameter must be present.
Theexpand
parameter can be used to include additional data in the response.
This can currently be set to attributes
, to include the user's attributes in the responseRequest
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user |
key | string | the key of the user (only observed if userName is null). |
Responses
- Status
200the representation of the found user
Example
{"expand":"attributes","link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user?username=sampleuser","rel":"self"},"name":"sampleuser","password":{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/password?username=sampleuser","rel":"edit"}},"key":"557057:927441f1-cc92-4030-b633-8a2bbdf7136e","active":true,"attributes":{"attributes":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts","rel":"self"},"name":"invalidPasswordAttempts","values":["0"]},{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"},"name":"requiresPasswordChange","values":["false"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"}},"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"}
- Status
404when the user cannot be found
Add userPOST /rest/usermanagement/1/user
Creates a new user
Request
Example
{"name":"sampleuser","password":{"value":"secret"},"active":true,"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"}
Responses
- Status
201the user was successfully created
Example
{"expand":"attributes","link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user?username=sampleuser","rel":"self"},"name":"sampleuser","password":{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/password?username=sampleuser","rel":"edit"}},"key":"557057:927441f1-cc92-4030-b633-8a2bbdf7136e","active":true,"attributes":{"attributes":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts","rel":"self"},"name":"invalidPasswordAttempts","values":["0"]},{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"},"name":"requiresPasswordChange","values":["false"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"}},"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"}
- Status
400invalid user data, for example missing password or the user already exists
- Status
403the application is not allowed to create a new user
Get user attributesGET /rest/usermanagement/1/user/attribute
Retrieves a list of user attributes
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user |
Responses
- Status
200
Example
{"attributes":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts","rel":"self"},"name":"invalidPasswordAttempts","values":["0"]},{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"},"name":"requiresPasswordChange","values":["false"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"}}
- Status
404the user could not be found
Store user attributesPOST /rest/usermanagement/1/user/attribute
Stores the user attributes. Attribute values will not be overwritten if not specified in attributes.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user |
Example
{"attributes":[{"name":"invalidPasswordAttempts","values":["0"]},{"name":"requiresPasswordChange","values":["false"]}]}
Responses
- Status
204the attributes were successfully updated
- Status
403the application is not allowed to set attributes
- Status
404the user could not be found
Remove user attributeDELETE /rest/usermanagement/1/user/attribute
Deletes a user attribute.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user |
attributename | string | name of the attribute to delete |
Responses
- Status
204the attributes was successfully deleted, or the attribute was not defined for the user
- Status
403the application is not allowed to delete attributes
- Status
404the user could not be found
Get avatar for user
experimentalGET /rest/usermanagement/1/user/avatar
Returns the url of the user's avatar
Request
query parameters
parameter | type | description |
---|---|---|
username | string | the name of the user |
s | int Default: 128 | the requested avatar size in pixels |
Responses
- Status
303the uri for the user's avatar (in the location header)
- Status
404the user doesn't exist, or doesn't have an avatar defined
Expire all passwords
experimentalPOST /rest/usermanagement/1/user/expire-all-passwords
Expires all passwords for all directories which are part of this application, regardless of group mapping.
Request
query parameters
parameter | type | description |
---|---|---|
confirm | boolean | must be true to take the action. This is so all passwords cannot accidentally be expired. |
Responses
- Status
500if any of the directories fail to expire all passwords. This can lead to only some of the users having expired passwords.
- Status
204the operation was successful
Get direct groupsGET /rest/usermanagement/1/user/group/direct
Returns the a list of groups the user is a direct member of.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user |
groupname | string | name of the group (optional). If null, then all the groups that the user is a direct member of, are returned. |
max-results | int Default: 1000 | maximum number of results to return |
start-index | int Default: 0 | start index of the result |
Responses
- Status
200
Example
{"expand":"group","groups":[{"link":{"href":"https://crowdserver/crowd/group?groupname=group&groupname=crowd-administrators","rel":"self"},"name":"crowd-administrators"}]}
- Status
404the user could not be found or the user is not a direct member of the specified group.
Add user to groupPOST /rest/usermanagement/1/user/group/direct
Adds a user as a direct member of the group
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user |
Responses
- Status
201the user was successfully added to the group
- Status
400the group could not be found
- Status
403the application is not allowed to add the membership
- Status
404the user could not be found
- Status
409the user is already a direct member of the group
Remove user from groupDELETE /rest/usermanagement/1/user/group/direct
Removes a user from a group.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user |
groupname | string | name of the group |
Responses
- Status
204the user was successfully removed from the group
- Status
403the application is not allowed to delete the membership
- Status
404the user or group could not be found
Get nested groupsGET /rest/usermanagement/1/user/group/nested
Retrieves the group that the user is a nested member of
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user |
groupname | string | name of the group (optional). If null, then all the groups that the user is a nested member of, are returned. |
max-results | int Default: 1000 | maximum number of results to return |
start-index | int Default: 0 | start index of the result |
Responses
- Status
200
Example
{"expand":"group","groups":[{"link":{"href":"https://crowdserver/crowd/group?groupname=group&groupname=crowd-administrators","rel":"self"},"name":"crowd-administrators"}]}
- Status
404the user could not be found or the user is not a nested member of the specified group.
Get user by openid
experimentalGET /rest/usermanagement/1/user/id
Looks up a user by the v2 OpenID URL, and returns the user's details
Request
query parameters
parameter | type | description |
---|---|---|
openid | string | the v2 OpenID URL for the user |
Responses
- Status
200the representation of the found user
Example
{"expand":"attributes","link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user?username=sampleuser","rel":"self"},"name":"sampleuser","password":{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/password?username=sampleuser","rel":"edit"}},"key":"557057:927441f1-cc92-4030-b633-8a2bbdf7136e","active":true,"attributes":{"attributes":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts","rel":"self"},"name":"invalidPasswordAttempts","values":["0"]},{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"},"name":"requiresPasswordChange","values":["false"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"}},"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"}
- Status
404the user was not found, or the provided url is not a v2 OpenID URL
Request password resetPOST /rest/usermanagement/1/user/mail/password
Sends the user a password reset link to the user's email address
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user to request a password reset |
Responses
- Status
204the operation was successful
- Status
403the application is not allowed to update the user's password
- Status
404the user could not be found
Request usernames reminderPOST /rest/usermanagement/1/user/mail/usernames
Requests an email to be sent containing usernames associated with the given email address.
Request
query parameters
parameter | type | description |
---|---|---|
email | string | email address of the user |
Responses
- Status
204the operation was successful
- Status
404no users with the given email were found
Update user passwordPUT /rest/usermanagement/1/user/password
Updates a user password.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | the name of the user to update the password for |
Example
{"value":"hunter2"}
Responses
- Status
204the password was updated
- Status
403the application is not allowed to update a user's password
- Status
404the user could not be found
Delete user passwordDELETE /rest/usermanagement/1/user/password
Deletes a user password. This will prevent the user from logging in using a password.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | the name of the user to update the password for |
Responses
- Status
204the password was updated
- Status
403the application is not allowed to update a user's password
- Status
404the user could not be found
Rename userPOST /rest/usermanagement/1/user/rename
Renames a user.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | name of the user to rename |
Example
{"new-name":"sampleuser-brandnewname"}
Responses
- Status
200the user was successfully renamed
Example
{"expand":"attributes","link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user?username=sampleuser","rel":"self"},"name":"sampleuser","password":{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/password?username=sampleuser","rel":"edit"}},"key":"557057:927441f1-cc92-4030-b633-8a2bbdf7136e","active":true,"attributes":{"attributes":[{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts","rel":"self"},"name":"invalidPasswordAttempts","values":["0"]},{"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"},"name":"requiresPasswordChange","values":["false"]}],"link":{"href":"https://crowdserver/crowd/rest/usermanagement/1/user/attributes?username=sampleuser&attributename=invalidPasswordAttempts&attributename=requiresPasswordChange","rel":"self"}},"first-name":"Sample","last-name":"User","display-name":"Sample User","email":"sample@user.cool"}
- Status
400the new user name is invalid or already taken
- Status
403the application is not allowed to rename the user
- Status
404the user could not be found