REST API - Users
General informations
Available for confluence administrators
Available since v. 1.2.0
- Get all users
- Add user
- Change user name
- Change user details
- Delete user
- Activate/deactivate user
Available since v. 2.0.0
- Get user property
- Set user property
Set avatar for any user
Available since v. 2.0.1
- Get user details
Available since v. 2.0.1
- Get user details
Available since v. 2.3.0
- Get all users - added optional parameter showDetails
- Get user details - added new fields - last login, created and updated date
Available since v. 2.7.0
- Added hasAccessToUseConfluence to getUsers and getUserDetails details
Available since v. 2.8.0
- Get all users - removed parameter showDetails, added parameters showBasicDetails and showExtendedDetails
Available since v. 2.13.0
- Add user - added sendMail flag; password is now optional
Get all users
This API supports Pagination
This API supports optional parameters
This API returns all only users with access to use Confluence
Method type - GET
URL
- {CONFLUENCE_URL}/rest/extender/1.0/user/getUsers
- {CONFLUENCE_URL}/rest/extender/1.0/user/getUsers?&showBasicDetails=true
- {CONFLUENCE_URL}/rest/extender/1.0/user/getUsers?&showExtendedDetails=true
Parameters:
showBasicDetails, showExtendedDetails - for details please check Example response
- dateFormat - define date format for date fields in output JSON - default format ‘yyyy-MM-dd'
Response format - JSON
Example response:
Without parameters
{
"total": 2,
"maxResults": 50,
"startAt": 0,
"users": [
{
"name": "new_user"
},
{
"name": "admin"
}
]
}
With parameter showBasicDetails=true
{
"total": 2,
"maxResults": 50,
"startAt": 0,
"users": [
{
"name": "new_user",
"fullName": "New user",
"key": "4128810272455d7b0172457188c10000",
"email": "new@user.pl"
},
{
"name": "admin",
"fullName": "admin",
"key": "4128810272455d7b0172457188c10005",
"email": "admin@admin.com"
}
]
}
With parameter showExtendedDetails=true
"total": 1,
"maxResults": 50,
"startAt": 0,
"users": [
{
"business": [
{
"location": "",
"position": "",
"department": ""
}
],
"lastFailedLoginDate": null,
"lastSuccessfulLoginDate": null,
"fullName": "Admin CEO",
"personal": [
{
"website": "",
"im": "",
"phone": ""
}
],
"updatedDate": 1590302967994,
"lastFailedLoginDateString": null,
"createdDate": 1590302967994,
"createdDateString": "2020-05-24 08:49:27",
"name": "Admin",
"lastSuccessfulLoginDateString": null,
"key": "4128810272455d7b0172457188c10000",
"email": "admin@admin.com",
"updatedDateString": "2020-05-24 08:49:27",
"hasAccessToUseConfluence": true
}
]
}
Get user details
This API supports optional parameters
Method type - GET
URL:
- {CONFLUENCE_URL}/rest/extender/1.0/user/getUserDetails/{userName}
where {userName} is user name like 'admin'
Parameters:
dateFormat - define date format for date fields in output JSON - default format ‘yyyy-MM-dd'
Example URL:
{CONFLUENCE_URL}/rest/extender/1.0/user/getUserDetails?dateFormat=MM/dd/yyyy
{CONFLUENCE_URL}/rest/extender/1.0/user/getUserDetails?dateFormat=dd.MM.yyyy
Response format - JSON
Example response:
{
"key": "2c9d829d6e61f011016e61f143ff0000",
"email": "admin@example.com",
"name": "admin",
"fullName": "admin admin",
"business": [
{
"location": "Poland",
"position": "CEO",
"department": "IT"
}
],
"personal": [
{
"website": "http://www.itlab.net.pl",
"im": "IM1234",
"phone": "0123456789"
}
],
"lastSuccessfulLoginDate": 1590039269342,
"lastSuccessfulLoginDateString": "2020-05-21 07:34:29",
"updatedDate": 1573637231865,
"updatedDateString": "2019-11-13 10:27:11”,
"lastFailedLoginDate": null,
"lastFailedLoginDateString": null,
"createdDate": 1573637231865,
"createdDateString": "2019-11-13 10:27:11",
"hasAccessToUseConfluence": true
}
Add user
Method type - PUT
URL:
{CONFLUENCE_URL}/rest/extender/1.0/user/add
Request format - JSON
Example
{
"name":"USER_NAME",
"fullName":"FULL NAME",
"email":"EMAIL",
"password":"PASSWORD",
"sendMail": true,
"groups": ["GROUP_1","GROUP_2"]
}
- name - required
- fullName - required
- email - required
- password - optional
- sendMail - optional - true or false - send an email message informing the person of their account (name, fullName and password)
- groups - optional - since v. 2.4.1 user is added to the default Confluence group, if you want to add it to another group, add this parameter
Response format - JSON
Example
{
"message": "User USER_NAME (FULL_NAME) was created"
}
Change user name
Method type - POST
URL:
{CONFLUENCE_URL}/rest/extender/1.0/user/rename/{userName}
where {userName} is user name
Example URL:
- {CONFLUENCE_URL}/rest/extender/1.0/user/rename/test_user
Request format - JSON
Example
{
"name":"test_user_new_name"
}
Response format - JSON
Example
{
"message": "User name 'test_user' was changed into 'test_user_new_name'"
}
Change user details
Method type - POST
URL:
{CONFLUENCE_URL}/rest/extender/1.0/user/changeDetails/{userName}
where {userName} is user name
Request format - JSON
Example
{
"fullName":"NEW_FULL_NAME",
"email":"NEW_EMAIL@test.pl",
"password":"NEW_PASSWORD"
}
- fullName - required
- email - required
- password - required
One parameter is required for this request
Response format - JSON
Example
{
"message": "User 'test_user' was changed"
}
Delete user
Method type - DELETE
URL:
{CONFLUENCE_URL}/rest/extender/1.0/user/delete/{userName}
where {userName} is user name
Response format - JSON
{
"message": "User USER_NAME (FULL NAME) was deleted"
}
Activate/deactivate user
Method type - POST
URL:
{CONFLUENCE_URL}/rest/extender/1.0/user/activate/{userName}{CONFLUENCE_URL}/rest/extender/1.0/user/deactivate/{userName}
where {userName} is user name
Response format - JSON
{
"message": "User USER_NAME (FULL NAME) deactivated"
}
Get user property
Method type - GET
URL:
{CONFLUENCE_URL}/rest/extender/1.0/user/property/{userName}/{propertyKey}
where {userName} is user name and {propertyKey} is property key
Example:
- {CONFLUENCE_URL}/rest/extender/1.0/user/property/admin/user.organisation.position.full.name
Response format - JSON
{
"value": "Chief Information Officer"
}
Set user property
Method type - PUT
URL:
{CONFLUENCE_URL}/rest/extender/1.0/user/property/{userName}/{propertyKey}
where {userName} is user name and {propertyKey} is property key
Request format - JSON
Example:
- {CONFLUENCE_URL}/rest/extender/1.0/user/property/admin/user.organisation.position.full.name
{
"value":"VALUE TO SET FOR THIS PROPERTY KEY"
}
Response format - JSON
{
"message": "success"
}
Set avatar for any user
Using base64 image
Method type - PUT
URL:
{CONFLUENCE_URL}/rest/extender/1.0/avatar/base64/{userName}
where {userName} is user name
Request format - JSON
Example:
- {CONFLUENCE_URL}/rest/extender/1.0/user/avatar/base64/rick
{
"string":"BASE64_IMAGE"
}
Response format - JSON
{
"message": "avatar changed"
}
Using image from disk
Method type - PUT
URL:
{CONFLUENCE_URL}/rest/extender/1.0/avatar/image/{userName}
where {userName} is user name
Request format - FILE FROM DISK
Curl example:
curl -D- -u {username}:{password} -X PUT -F "file=@{PATH/TO/FILE}" {CONFLUENCE_URL}/rest/extender/1.0/user/avatar/image/rick
Postman example:
In Body select form-data → In KEY write file and select image in VALUE
Response format - JSON
{
"message": "avatar changed"
}
Pagination
This REST API uses pagination to improve performance for all users. Pagination is enforced for methods that could return a large collection of items. When you make a request to a paged API, the response will wrap the returned array of values in a JSON object with paging metadata, for example:
{
"startAt" : 0,
"maxResults" : 10,
"total": 200,
"objects": [
{ /* result 0 */ },
{ /* result 1 */ },
{ /* result 2 */ }
]
}
Where:
startAtis the index of the first item returned in the page of results.maxResultsis the maximum number of items that can be returned per page. Each API endpoint may have a different limit for the number of items returned, and these limits may change without notice. (default value - 50)totalis the total number of items contained in all pages. This number may change as the client requests the subsequent pages, therefore the client should always assume that the requested page can be empty.