Provisioning API – Authentication

Overview

The SearchStax Managed Search service provides an API supporting the creation, deletion, and management of Solr 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.

The Provisioning API uses two methods of authentication appropriate to two levels of security:

Token Authentication: Use the username and password of an authorized user to obtain an authentication token. The token authorizes API calls within the normal scope of the user’s permissions. A token expires after 24 hours.
API Key Authentication: The API Key authenticates a narrow set of API functions for managing Solr Basic Auth users and Zookeeper configurations in a deployment. The API Key does not expire, but it can be revoked.

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:

Token Authentication
- obtain-auth-token > create
API Key Authentication

Token Authentication

The first step in using the SearchStax API is to obtain an authentication token by logging in to the SearchStax server. The token authorizes subsequent API requests.

obtain-auth-token > create

Generates an authentication token for the user of a tenant account. This token can be used to authenticate Searchstax API calls for up to 24 hours.

POST https://app.searchstax.com/api/rest/v2/obtain-auth-token/

The request body should be an “application/x-www-form-urlencoded” object to accommodate the non-alphanumeric characters that sometimes appear in user names and passwords.

"username=<username>&password=<password>"

Parameter	Description	Example
username required string	This is the email address used when you log into the SearchStax server.	“user@company.com”
password required string	This is the password associated with that username.	“4r36%74m”
tfa_token optional string	This is a six-digit code supplied by the Google Authenticator to enable two-factor authentication. Each code is good for one minute, so move fast. The eight-character backup codes work with no time limit, but only once each. If TFA is not enabled for this user account, this token is ignored.	“123456” or “noho2x5n”

When invoked from Linux (Bash script):

TOKEN=$(curl -s -H "Content-Type: application/json" -X POST \
       -d "{\"username\":\"$USER\",\"password\":\"$PASSWORD\",\"tfa_token\":\"$TWOFACTOR\"}" \
       https://app.searchstax.com/api/rest/v2/obtain-auth-token/)

If SearchStax will not accept your credentials from Bash, check your password for a $ or # character. Bash will try to interpret these characters, changing the text of the password.

When invoked from Windows (PowerShell script):

$USER = "username"
$PASSWORD = "password"
$TFA = "123456"

$body = @{
    username=$USER
    password=$PASSWORD
    tfa_token=$TFA
}

$body = $body | ConvertTo-Json

$TOKEN = Invoke-RestMethod -Method Post -Body $body -ContentType 'application/json' `
        -uri "https://app.searchstax.com/api/rest/v2/obtain-auth-token/" 
$TOKEN = $TOKEN.token

The response is a JSON document containing an authorization token.

{
  "token": "aa70cb0a180a0532ae8855f7a1712eeceb81e080"
}

Using the token in Bash

In the Bash scripts, the authorization token is incorporated directly in the header of the cURL call:

    curl -s -H "Authorization: Token $TOKEN" etc.

Using the token in PowerShell

In the PowerShell scripts, we use the token by assembling a header for the Invoke-RestMethod call. Note that $TOKEN.token extracts the actual token number from the Json response.


$TOKEN = $TOKEN.token

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "Token $TOKEN")

$RESULTS = Invoke-RestMethod -Headers $headers etc.

API Key Authentication

An API Key is a non-expiring authorization allowing certain non-SearchStax users to perform a specific set of API operations on specific deployments of a specific account. If you step outside of that scope, you will see an Out of Scope error.

In a little more detail:

You must be the Owner or an Admin of a Platinum or Platinum Plus account to generate an API Key.
You will need Token Authentication to create the API Key.
The API Key by itself is not good for anything. The account Owner or an Admin must associate the API Key with a specific deployment before the key becomes active.
At this point, anyone who possesses the API Key (anyone at all) can use SearchStax Provisioning API methods to:
- Manage Solr Basic Auth users on that specific deployment.
- Manage Solr configurations on Zookeeper in that specific deployment.

Note that the API Key is good for absolutely nothing else.

Procedure for creating an APIkey:

Obtain an authentication Token.
Generate an APIkey.
Associate the APIkey with a specific deployment.

Once the APIkey has been associated with a deployment, you can view the APIkey under the Security menu for that deployment in the Managed Search dashboard.

account > apikey > create

This method creates an API Key based on a valid authentication token.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/

where <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:

{
    "scope":["deployment.dedicateddeployment"]
}

Parameter	Description
scope required list of strings	The scope in which this API key will be effective. Default value is deployment.dedicateddeployment.

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{
    \"scope\":[\"deployment.dedicateddeployment\"]
}"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$body = @{
    scope=@('deployment.dedicateddeployment')   # Force single-value to be a list
}
$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/apikey/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document:

{ "apikey": "eyJhbGciOiJIUzVCJ9.eyJpYXQiOjE1NDMyNDc0ODMsImp0aSI6IjhmYTlkZThjNTIyNjRjZTc2Njg0NTkyMWQ4MTQ0MDY5ZThkMjc5NmMiLCJzY29wZSI6WyJkZXBsb3ltZW50LmRlZGljYXRlZGRlcGxveW1lbnQiXSwiQ1MrdThSZmlNTzMwNnZJM082QSJ9.r6X7bJi_ZWGR99XC0Ac" }

Using the API key in Bash

In the Bash scripts, we use the API key directly in the header of the cURL call:

 curl -s -H "Authorization: APIkey $APIKEY" etc.

Using the API key in PowerShell

In the PowerShell scripts, we use the API key by assembling a header and using it in the Invoke-RestMethod call:

 $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "APIkey $APIKEY")

$RESULTS = Invoke-RestMethod -Headers $headers etc.

account > apikey > associate_apikey_to_deployment

This method associates an API key to a specific deployment. Note that an API key can be associated with multiple deployments, but each deployment can be associated with only one API key at a time.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/associate/

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

This method requires Token authentication.

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

{
    "apikey": "eyJhbGciOiJI6IkpXVCJ9...",
    "deployment": "ss123456"
}

Parameter	Description	Example
apikey required string	This is the API key that needs to be associated with the deployment.	“eyJhbGciOiJI6IkpXVCJ9…”
deployment required string	This is the UID of the deployment.	“ss123456”

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/associate/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{
    \"apikey\": \"eyJhbGciOiJI6IkpXVCJ9...\",
    \"deployment\": \"ss123456\"
}"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$body = @{
    apikey=$APIKEY
    deployment=$uid
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod  -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/apikey/associate/"

$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing a list of deployments associated with this key.

{
  "deployments": [ "ssXXXXX1", "ssXXXXX2"]
}

account > apikey > apikey_deployments

This method lists the deployments associated with the given API key.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/deployments/

where <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:

{
    "apikey" : "eyJhbGciOiJI6IkpXVCJ9..."
}

Parameter	Description	Example
apikey required string	This is the API key that is associated with the deployments.	“eyJhbGciOiJI6IkpXVCJ9…”

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/deployments/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{ \"apikey\" : \"eyJhbGciOiJI6IkpXVCJ9...\" }"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$APIKEY = "eyJhbGciOiJI6IkpXVCJ9..."

$body = @{
    apikey=$APIKEY
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/apikey/deployments/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing a list of deployment UIDs.

{
  "deployments": [ "ss123456" ]
}

account > apikey > disassociate_apikey_from_deployment

This method disassociates an API key from a deployment.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/disassociate/

where <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:

{
    "apikey" : "eyJhbGciOiJI6IkpXVCJ9...",
    "deployment": "ss123456"
}

Parameter	Description	Example
apikey required string	This is the API key that needs to be disassociated from the deployment.	“eyJhbGciOiJI6IkpXVCJ9…”
deployment required string	This is the UID of the deployment.	“ss123456”

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/disassociate/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{
    \"apikey\" : \"eyJhbGciOiJI6IkpXVCJ9...\",
    \"deployment\": \"ss123456\"
}"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$APIKEY = "eyJhbGciOiJI6IkpXVCJ9..."

$body = @{
    apikey=$APIKEY
    deployment=$uid
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/apikey/disassociate/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing a list of deployments with which the API key is still associated.

{
  "deployments": [
    "ssXXXXX1",
    "ssXXXXX2",
    "ssXXXXX3"
  ]
}

account > apikey > deployment_apikeys

This method lists the API key that is associated with a deployment. Each deployment may be associated with only one API key at a time.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/list/

where <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:

{
    "deployment" : "ss123456"
}

Parameter	Description	Example
deployment required string	This is the UID of the deployment.	“ss123456”

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/list/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{ \"deployment\" : \"ss123456\" }"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$body = @{
    deployment=$uid
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/apikey/list/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing the API key associated with the deployment.

{
  "apikey": [ "eyJhbGciOiJI6IkpXVCJ9..." ]
}

account > apikey > revoke

This method revokes an API key.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/revoke/

where <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:

{
    "apikey" : "eyJhbGciOiJI6IkpXVCJ9..."
}

Parameter	Description	Example
apikey required string	This is the API key to revoke.	“eyJhbGciOiJI6IkpXVCJ9…”

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/apikey/revoke/" \
  --header "Authorization: Token <token>" \
  --header "Content-Type: application/json" \
  --data "{
    \"apikey\" : \"eyJhbGciOiJI6IkpXVCJ9...\"
}"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$APIKEY = "eyJhbGciOiJI6IkpXVCJ9..."

$body = @{
    apikey=$APIKEY
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/apikey/revoke/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing a success/failure message.

{
  "success": "API Key revoked successfully."
}

Questions?

Do not hesitate to contact the SearchStax Support Desk.