You are using an unsupported browser. Please update your browser to the latest version on or before July 31, 2020.
Home > Technology and Integration > Whitespace API Integration > Getting a renewable token for API usage
Getting a renewable token for API usage
print icon

NOTE: this feature will only be enabled for specific logins and on request; by default it is not available.

For a refresh-enabled login account, the refresh token can be accessed via the 'User Profile' panel on the browser. We recommend accessing this immediately after logging on as it will be cleared by other verification processes during the session.

User Profile Screenshot

Clicking "Copy" will copy the refresh token to your computer's clipboard, allowing you to paste it to a secure location for use in the future.

Call an API GET on $SYNC/$BUCKET/_oidc_refresh?refresh_token=$RENEWABLE where SYNC and BUCKET are the correct values for the Couchbase Sync-Gateway API and bucket respectively, and RENEWABLE is the token copied above.

This returns the following JSON. Use the value of id_token in subsequent API calls.

  "id_token": "********",
  "session_id": "********",
  "name": "********"

For instance:

export TOKEN=`curl $SYNC/$BUCKET/_oidc_refresh?refresh_token=$RENEWABLE | jq -r .id_token`
curl -H "Authorization: Bearer $TOKEN" $API/risks


Single User, Multiple Organisations (SUMO)

When the user has been set up in multiple organisations an additional header needs to be passed to identify the unique account being used. This is passed in a header of the form "UserID: MUxxx" where MU is the unique identifier given to the user. The MU value can be fetched from a call to $API/shared/corporate which does not require the UserID header - you will need to search or the user in question. A call to $API/user/myDetails includes the MU value, but a SUMO user cannot run that endpoint without passing the MU value. Note that the MU value is persistent; if you make a note of it, then it can be used for that user forever.


If the UserID header is not supplied or is incorrect, the error given is:

curl -H "Authorization: Bearer $TOKEN" $API/risks


  "reason": "Invalid WSAUTH: Valid UserID must be supplied",

  "error": true


Setting the value and then using it in the UserID heading will work:

export UIMU=MU00000000-0000-0000-0000-000000000000

curl -H "Authorization: Bearer $TOKEN" -H "UserID:$UIMU" $API/risks



    "ContractType": "Non-Bulking Line Slip",

    "InsuredName": "AV Facility",

    "IsFacility": true,

    "Status": "Signed",

    "channels": [





To run the command for other organisations, simply pass a different UserID:


curl -H "Authorization: Bearer $TOKEN" -H "UserID:$UIMU" -s $API/risks | jq '. | length' # 1528 risks

export UIMU2=MU11111111-1111-1111-1111-111111111111

curl -H "Authorization: Bearer $TOKEN" -H "UserID:$UIMU2" -s $API/risks | jq '. | length' # 439 risks


1 out of 2 found this helpful

scroll to top icon