SearchStax Provisioning API - Authentication


Overview

SearchStax® provides an API supporting the creation, deletion and management of SearchStax deployments.

This page describes how to authenticate requests to API methods.

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:

Authentication

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

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"

When invoked from Linux (Bash script):

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

When invoked from Windows (PowerShell script):

$USER = "username"
$PASSWORD = "password"

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

$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/" 

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 and using it in the Invoke-RestMethod call:

$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.

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.