Provisioning API – Users

Overview

The SearchStax Managed Search service provides an API supporting the creation, deletion and management of SearchStax Managed Search service deployments.

Platinum and Platinum Plus Clients Only!

The SearchStax API suite is available to our Platinum and Platinum Plus clients only, as noted on our Pricing page.

This page describes how to manage the users of a SearchStax account through the API.

The API can be accessed through any tool that assembles HTTP requests and dispatch them to a server. Among these would be the Python coreapi package, the Postman tool, and cURL. For Windows, use PowerShell 7+.

Account Owner, Admin, or Technical Contact

To run the SearchStax Provisioning API, you must be the account Owner, an account Admin, or a Technical Contact. See SearchStax User Roles.

Symbols enclosed in carets (< and >) such as <username> are metavariables. Substitute your local values when you encounter them in the examples.

Contents:

Users

Users

The SearchStax Provisioning API provides methods for managing the users of a SearchStax Account from a remote application.

users > list

This method lists the SearchStax users for an account.

GET https://app.searchstax.com/api/rest/users/?account=<account_name>

where ?account=<account_name> is the name of the tenant account.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET https://app.searchstax.com/api/rest/users/?account=$ACCOUNT 
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/users/?account=$ACCOUNT" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing the SearchStax users of the account and their details:

{
  "success": true,
  "users": [
    {
      "firstname": "FirstName",
      "lastname": "LastName",
      "email": "user@company.com",
      "role": "Team Member",
      "phone": "123-456-7890",
      "company": "Company",
      "id": 3201,
      "last_login": null,
      "created": "2021-01-06T19:51:28Z",
      "invitation_status": "Completed"
    }
  ]
}

users > add-user > create

This method invites a new user to join an existing tenant account.

POST https://app.searchstax.com/api/rest/users/add-user?account=<account_name>

where ?account=<account_name> is the name of the tenant account.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    "email": "user@company.com",
    "role": "Admin",
    "first_name": "First",
    "last_name": "Last",    
    "phone_number": "8005551212"
}

Parameter	Description
email required string	The user’s email.
role required string	One of ‘Admin’, ‘Technical Contact’, ‘Billing Member’, ‘Team Member’.
first_name required string	User’s first name.
last_name required string	User’s last name.
phone_number optional string	User’s phone number.

When invoked from Linux (Bash script):

curl -s -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" -d "${BODY}" 
-X POST https://app.searchstax.com/api/rest/users/add-user?account=$ACCOUNT

When invoked from Windows (PowerShell script):

$body = @{
    email='clayton@sti.net'
    role='Admin'
    first_name='Bruce'
    last_name='Clayton'    
    phone_number='8005551212'
}

$body = $body | ConvertTo-Json

$RESULTS = Invoke-RestMethod -Method Post -Body $body -ContentType 'application/json' -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/users/add-user?account=$ACCOUNT" 
$RESULTS = $RESULTS | ConvertTo-Json

This method returns a JSON document containing a success message.

{
  "success": true,
  "message": "User 'user@company.com' invited successfully."
}

users > change-password > create

This method allows an authenticated user to change his own password. It is not possible to change someone else’s password.

POST https://app.searchstax.com/api/rest/users/change-password?account=<account_name>&id=<id>

where ?account=<account_name> is the name of the tenant account, and id=<id> is the user identification number obtained from users > list.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following item:

{
    "password": "new-password"
}

Parameter	Description
password required string	The desired new password.

When invoked from Linux (Bash script):

curl -s -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" -d "${BODY}" 
-X POST "https://app.searchstax.com/api/rest/users/change-password?account=$ACCOUNT&$ID"

When invoked from Windows (PowerShell script):

$body = @{
    password='password'
}

$body = $body | ConvertTo-Json

$RESULTS = Invoke-RestMethod -Method Post -Body $body -ContentType 'application/json' -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/users/change-password?account=$ACCOUNT&id=$ID" 
 
$RESULTS = $RESULTS | ConvertTo-Json

This method returns a JSON document containing a success message.

{
    "success":  true,
    "message":  "Password changed successfully."
}

If you received an error saying, “You can not change password for another user,” check to be sure the URL is within double-quotes. If not, everything to the right of the ampersand (&) will be truncated, usually resulting in the loss of the user ID.

users > set-role > create

This method allows an Author or Admin to change the role of one or more account users.

POST https://app.searchstax.com/api/rest/users/set-role/?account=<account_name>

where ?account=<account_name> is the name of the tenant account..

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following item:

{
    "id": "2178,2067,3385",
    "role": "Team Member"
}

Parameter	Description
id required string	A comma-separated list of user ID numbers obtained from users > list.
role required string	One of Admin, Technical Contact, Billing Member, Team Member. All listed users will be reassigned to the same role.

When invoked from Linux (Bash script):

curl -s -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" -d "${BODY}" 
-X POST "https://app.searchstax.com/api/rest/users/set-role?account=$ACCOUNT"

When invoked from Windows (PowerShell script):

$body = @{
    id='2178,2067,3385'
    role='Team Member'
}

$body = $body | ConvertTo-Json

$RESULTS = Invoke-RestMethod -Method Post -Body $body -ContentType 'application/json' -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/users/set-role?account=$ACCOUNT" 
 
$RESULTS = $RESULTS | ConvertTo-Json

This method returns a JSON document containing a success/failure message for each user.

[
  {
    "id": 2178,
    "success": true,
    "message": "Role updated successfully."
  },
  {
    "id": 2067,
    "success": false,
    "message": "User id 2067 does not exist."
  },
  {
    "id": 3385,
    "success": true,
    "message": "Role updated successfully."
  }
]

users > delete

This method deletes a SearchStax user from an Account.

DELETE https://app.searchstax.com/api/rest/users/?account=<account_name>&id=<user_id>

where ?account=<account_name> is the name of the tenant account, and &id=<user_id> is the ID of the user.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl -H "Content-Type: application/json" -H "Authorization: Token $TOKEN" 
     -X DELETE "https://app.searchstax.com/api/rest/users/?account=$ACCOUNT&id=$DELUSER"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$DELUSER = "1234"

$RESULT = Invoke-RestMethod -Method Delete -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/users/?account=$ACCOUNT&id=$DELUSER" 
$RESULT = $RESULT | ConvertTo-Json

This method returns a JSON document containing a success message.

{
   "id":3204,
   "success":true,
   "message":"User deleted successfully."
}

Questions?

Do not hesitate to contact the SearchStax Support Desk.