General Information

Please note that this is our private API, there might be breaking changes in upcoming versions. Please contact our support, if something does not work as expected anymore.

REST API

Below you will find some examples which you could use. You would need to change the following:

  • change '<base-url>' with your actual base URL
  • change '<connectorID>' with your connector ID (you can find it if you click on Edit on your connector and scroll down to the field)
  • change '<directoryID>' with your directory ID (below the connector id)




How to monitor the User Sync status via REST API?

Problem

We are looking for a REST API endpoint to monitor the User Sync status.

Solution

This article refers to our plugin version SAML Single Sign On 4.x. (User Sync 1.9)


You can use the REST API of the User Sync app which allows you to get the results from the last sync.

GET - result from last sync

curl -u username:password -X GET https://<base-url>/rest/samlsso-admin/1.0/usersync/connector/<connectorID>/syncstatus
CODE

More useful REST API examples

You also have the possibility to get some more information from your User Sync via REST API.

GET - show all connectors

Get all configured connectors (and the connector settings). This will also include the uniqueId which is the Connector ID. 

curl -u username:password -X GET https://<base-url>/rest/samlsso-admin/1.0/usersync/connector/
CODE

GET - connector ID

We have to use a JSON parser to extract the information. You can use, as an example, jq to do that (jq is a lightweight and command-line JSON processor). 

curl -u user:password -X GET https://<base-url>/rest/samlsso-admin/1.0/usersync/connector/ | jq '.[].uniqueId'
CODE

If you want to get rid of the double quotes, pass -r (--raw) to jq:

curl -u user:password -X GET https://<base-url>/rest/samlsso-admin/1.0/usersync/connector/ | jq -r '.[].uniqueId'
CODE

GET - show a connector

curl -u username:password -X GET https://<base-url>/rest/samlsso-admin/1.0/usersync/connector/<connectorID>
CODE

POST

The way the command works has changed for SAML version 5.x / User Sync 2.x. The data is now sent as a json.

POST - initiate a Sync (User Sync 2.x)

curl -X POST "https://<base-url>/rest/samlsso-admin/1.0/usersync/connector/<connectorID>/sync" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -u ‘username:password’
CODE

POST - initiate a Single User Update (User Sync 2.x)

curl -X POST "https://<base-url>/rest/samlsso-admin/1.0/usersync/connector/<connectorID>/syncsingle" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -u ‘username:password’ \
  -d $'{"identifier": "<user-indentifier>"}'
CODE

POST - initiate a Single User Update with the Option Sync With Username As Primary Attribute (User Sync 2.x)

curl -X POST "https://<base-url>/rest/samlsso-admin/1.0/usersync/connector/<connectorID>/syncsingle" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -u 'username:password' \
  -d '{"identifier": "<user-indentifier>", "overridePrimaryAttributeWithUsername": true}'
CODE

POST - initiate a sync (User Sync 1.9)

curl -u username:password -X POST https://<base-url>/rest/samlsso-admin/1.0/usersync/connector/<connectorID>/sync
CODE

POST - initiate a Single User Update (User Sync 1.9)

curl -u username:password -X POST https://<base-url>/rest/samlsso-admin/1.0/usersync/connector/<connectorID>/syncsingle/<username>
CODE


DELETE - delete a directory

The REST API command will delete a User Directory in your Atlassian instance. This will also include a deletion of all users which were part of the directory! There will be no warning! Use with care.


curl -u username:password -X DELETE https://<base-url>/rest/samlsso-admin/1.0/directory/<directoryID>
CODE

Creation

There is a way to create your deleted directory. Please note you can not start a new Sync from your User Sync Connector, this will fail with the following message:

Scheduled with jobid d8dc7879-1b15-4dcd-98b6-64eb5c30e2f1
Directory <directoryID> does not exists
CODE
  1. Choose the Connector Name from which you want to create a new directory. You have to click 'Edit' and 'Save' your connector settings (User Sync → Edit Connector → Save). This will create a User Directory (directory ID) again.
  2. Now you can start a 'Sync' again and the user directory will be filled with user data