Back

API Overview

Authentication

All requests to Soltra Edge require you to authenticate. There are several ways to authenticate to the REST API:

  • Basic Authentication with your Soltra Edge username and Password
  • Token Authentication with a generated Personal Access Token
  • Session Authentication from your browser

Basic Authentication:

curl -u username:password 'https://edge-domain.com/api/stix/'

or via Browser:

https://username:password@edge-domain.com/api/stix/

Basic Authentication is useful for interactively exploring the API via curl or your browser. However, for setting up machine-to-machine services, it is highly recommended that you use a Token based authentication mechanism.

Note:  If your password contains special characters, you’ll need to manually escape each one with backslashes when using curl. So, for example, a password of P@$$word would be encoded as `curl -u username:P@$$word `. Each special character must be preceded by a ``

Token Authentication:

curl -H "Authorization: Token <b64encoded(username:token)>" https://edge-domain.com/api/stix/

The REST API uses Personal Access Tokens for authentication. They function like OAuth tokens and can be used in place of a password. Tokens enable you to have multiple sets of credentials active at once, control each of their access individually, and revoke them when needed.

Like HTTP Basic Auth, Tokens are sent as a base64 encoded string in the Authorization header.

Authorization: Token YWRtaW46MDNiYThmMGZiNGExZDZmNGU2MzRmYmFiYjY4YWQ3YjY5ZTdiZDRmMA==

Example: building the Authorization Header

The following will use “admin” as the username and “03ba8f0fb4a1d6f4e634fbabb68ad7b69e7bd4f0” as the token value.

Note: see the Administration of the docs for instructions on generating new tokens.

Command Line

Step 1:

Combine the username and token into a single string separated by a colon

admin:03ba8f0fb4a1d6f4e634fbabb68ad7b69e7bd4f0

Step 2:

Base64 encode the string

$ echo -n 'admin:03ba8f0fb4a1d6f4e634fbabb68ad7b69e7bd4f0' | base64
result: YWRtaW46MDNiYThmMGZiNGExZDZmNGU2MzRmYmFiYjY4YWQ3YjY5ZTdiZDRmMA==

Step 3:

Finally, combine the base64 encoded username:token combination with the string "Token"

Token YWRtaW46MDNiYThmMGZiNGExZDZmNGU2MzRmYmFiYjY4YWQ3YjY5ZTdiZDRmMA

This will be the string you send in the Authorization header.

e.g.

curl -H "Authorization Token YWRtaW46MDNiYThmMGZiNGExZDZmNGU2MzRmYmFiYjY4YWQ3YjY5ZTdiZDRmMA"

Python

from base64 import b64encode

username = 'admin'
token = '03ba8f0fb4a1d6f4e634fbabb68ad7b69e7bd4f0'

# Combine the username and token into a single string separated by a colon
username_token = '{username}:{token}'.format(username=username, token=token)
# Base64 encode the string
b64encoded_string = b64encode(username_token)
# Combine the string "Token" with the b64encoded username:token combo
auth_string = 'Token {}'.format(b64encoded_string)

full_header = 'Authorization: {}'.format(auth_string)

print(full_header)
'Authorization: Token YWRtaW46MDNiYThmMGZiNGExZDZmNGU2MzRmYmFiYjY4YWQ3YjY5ZTdiZDRmMA'

Hypermedia

Nested resources and options are provided in the response via *_url fields. It is recommended to use these fields versus building your own URIs as not all STIX endpoints have the same options. For example, traversing related``objects for indicators and Threat Actors` makes different options available in the response (note the different endpoints):

Indicators

{
        "url": "/adapter/stix_api/v1/stix/opensource%3Aindicator-d6bd5d04-ff29-449d-9aba-e78e634d2db5/related/",
        "related_campaigns_url": "/adapter/stix_api/v1/stix/opensource%3Aindicator-d6bd5d04-ff29-449d-9aba-e78e634d2db5/related/campaigns",
        "related_coas_url": "/adapter/stix_api/v1/stix/opensource%3Aindicator-d6bd5d04-ff29-449d-9aba-e78e634d2db5/related/coas",
        "related_indicators_url": "/adapter/stix_api/v1/stix/opensource%3Aindicator-d6bd5d04-ff29-449d-9aba-e78e634d2db5/related/indicators",
        "related_ttps_url": "/adapter/stix_api/v1/stix/opensource%3Aindicator-d6bd5d04-ff29-449d-9aba-e78e634d2db5/related/ttps"
    }

Threat Actors:

{
"related_campaigns_url": "/adapter/stix_api/v1/stix/MyEdge%3Athreatactor-ca66d0b0-6fb7-479e-a61c-4e3ae738462c/related/campaigns",
        "related_threat_actors_url": "/adapter/stix_api/v1/stix/MyEdge%3Athreatactor-ca66d0b0-6fb7-479e-a61c-4e3ae738462c/related/threat_actors",
        "related_ttps_url": "/adapter/stix_api/v1/stix/MyEdge%3Athreatactor-ca66d0b0-6fb7-479e-a61c-4e3ae738462c/related/ttps"
}