SearchStax Managed Solr Provisioning API – Authentication
Overview
SearchStax provides an API supporting the creation, deletion, and management of Managed 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 Core 6.1+.
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:
Related Pages:
- Users API
- Basic Auth API
- IP Filtering API
- Deployment API
- Private VPC API
- DNS Alias API
- Backup/Restore API
- Tags API
- Alerts API
- Webhooks API
- Zookeeper API
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/)
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 giving an external user a limited ability to manage his own Zookeeper configurations and Solr Basic Auth users. It is created by a SearchStax Admin using an Authentication Token.
Procedure for creating an APIkey:
Once the APIkey has been associated with a deployment, you can view the APIkey under the Security menu for that deployment in the Managed Solr 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/" <strong>\
</strong> --header "Authorization: Token <token>" <strong>\
</strong> --header "Content-Type: application/json" <strong>\
</strong> --data "{
<strong>\"</strong>apikey<strong>\"</strong>: <strong>\"</strong>eyJhbGciOiJI6IkpXVCJ9...<strong>\"</strong>,
<strong>\"</strong>deployment<strong>\"</strong>: <strong>\"</strong>ss123456<strong>\"</strong>
}"
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/" <strong>\
</strong> --header "Authorization: Token <token>" <strong>\
</strong> --header "Content-Type: application/json" <strong>\
</strong> --data "{
<strong>\"</strong>apikey<strong>\"</strong> : <strong>\"</strong>eyJhbGciOiJI6IkpXVCJ9...<strong>\"</strong>,
<strong>\"</strong>deployment<strong>\"</strong>: <strong>\"</strong>ss123456<strong>\"</strong>
}"
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.