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:

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

Authentication

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.

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.

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 SearchStax Dashboard.

SearchStax APIkey menu

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.

Free Trial

Getting Started

Integrate Solr with...

Cloud Manager

Private Cloud

Pulse/Monitoring

Search Analytics

SearchStax API

Third-Party Integration

Accounts and Billing

Support Guide

SearchStax Provisioning API - Authentication

Overview

Authentication

Token Authentication

obtain-auth-token > create

API Key Authentication

account > apikey > create

account > apikey > associate_apikey_to_deployment

account > apikey > apikey_deployments

account > apikey > disassociate_apikey_from_deployment

account > apikey > deployment_apikeys

account > apikey > revoke

Questions?