search close

Using Our API

access_time Updated Jun 20, 2021

Our entire console is built API-first — this means that anything we can do, you can do as well via our API, which is fully documented here.

We’ve seen customers use our API a number of ways, but a common use case is importing our request data into a SIEM like Splunk or Kibana which can allow you to more easily correlate our security data with your internal data.

About API Access Tokens

Users can connect to the API by creating and using personal API Access Tokens. Authenticate against our API using your email and access token.

By default, all users have the ability to create and use API Access Tokens. However, Owner Users can choose to restrict API Access Token creation and usage to specific users. All plans allow you to create up to 5 access tokens per user.

Managing API Access Tokens

Creating API Access Tokens

  1. Go to My Profile > API Access Tokens

  2. Click Add API access token

  3. Enter a name to identify the access token and click Create API access token

  4. The new token will be displayed. Record the token in a secure location for your use.

    Note: This is the only time the token will be visible. Record the token and keep it secure. For your security, it will not be displayed in the console.

  5. Click Continue to finish creating the token

Restricting User Permission to Create and Use API Access Tokens

Owner Users can restrict all users from creating and using API Access Tokens. After doing so, Owner Users can then manually grant specific users permission to create and use API Access Tokens.

API Access Tokens that were created before restrictions were activated will not be deleted. However, the users with existing tokens will need to be given permission to use API Access Tokens. Until a user is again granted permission to use API Access Tokens, the token will remain in a disabled state. After a user has been granted permission, the console will remember that permission moving forward.

Owner Users can enable API Access Token restrictions by following these steps:

  1. Go to Corp Manage > User Authentication

  2. Scroll down to the section labeled API Access Tokens.

  3. Under Access token permissions, click the toggle for Restrict access by user

  4. A message will be displayed warning you about this setting and its restrictions. Click Continue to proceed.

  5. Click Update API Access Tokens at the bottom to save this change

Granting Users Permission to Create and Use API Access Tokens

When API Access Token creation and usage is restricted, only Owner Users can enable other users to create API Access tokens.

Note: After restricting API Access Token usage, Owner Users will also need to grant themselves permission to create and use API Access Tokens.

  1. Go to Corp Manage > Corp Users

  2. Click on the user you want to grant permission to

  3. Click Edit corp user at the top

  4. Under Authentication check the box labeled Allow this user to create API Access Tokens

  5. Click Update user at the bottom

Deleting API Access Tokens

  1. Go to My Profile > API Access Tokens

  2. Click View to the far right of the token you want to delete

  3. Click Delete API access token

  4. Click Delete to confirm you want to delete the token

Viewing Personal API Tokens

Owner Users can view a table of all access tokens across your corp by going to Corp Manage > API Access Tokens. This table shows the various statuses of each token (active, expired, disabled by owner), their creators, IPs they were used by, and expiration dates.

Managing Corp-Wide API Access Token Settings

Setting Automatic Token Expirations

Owner Users can set API Access Tokens to automatically expire after a set period of time.

  1. Go to Corp Manage > User Authentication

  2. Scroll down to the section labeled API Access Tokens.

  3. Under Access token expiration, click the toggle for Custom expiration

  4. Select one of the default periods of time, or select Custom to set a specific custom period of time.

    The expiration is based on the creation date of the token itself, not from the start of the expiration policy. For example if there’s a 60-day-old token and you set a 30-day expiration policy, the token will instantly be expired. But if you later switch the expiration to 90 days, the token will be un-expired.

  5. Click Update API Access Tokens at the bottom to save this change

Restricting API Access Token Usage by IP

Owner Users can restrict the use of API Access Tokens to specific IP addresses.

  1. Go to Corp Manage > User Authentication

  2. Under API Access Tokens, there is a text box labeled Restrict usage by IP (optional)

  3. Enter the IP addresses and IP ranges you want to limit token usage to in the text box. IP addresses must each use a new line.

  4. Click Update API Access Tokens at the bottom to save this change

Using Personal API Access Tokens

Golang

package main

import (
	"encoding/json"
	"fmt"
	"io/ioutil"
	"log"
	"net/http"
	"os"
	"time"
)

var (
	// Defines the API endpoint
	endpoint = "https://dashboard.signalsciences.net/api/v0"
	email    = os.Getenv("SIGSCI_EMAIL")
	token    = os.Getenv("SIGSCI_TOKEN")
)

// Corp is a Signal Sciences corp
type Corp struct {
	Name         string
	DisplayName  string
	SmallIconURI string
	Created      time.Time
	SiteLimit    int
	Sites        struct {
		URI string
	}
	AuthType    string
	MFAEncorced bool
}

// CorpResponse is the response from the Signal Sciences API
// containing the corp data.
type CorpResponse struct {
	Data []Corp
}

func main() {
	// No need for timestamps or anything
	log.SetFlags(0)
	
	// Get corps
	req, err := http.NewRequest("GET", endpoint+"/corps", nil)
	if err != nil {
		log.Fatal(err)
	}

	// Set headers
	req.Header.Set("x-api-user", email)
	req.Header.Set("x-api-token", token)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Add("User-Agent", "SigSci Go-Example")

	// Make request
	var transport http.RoundTripper = &http.Transport{}
	response, err := transport.RoundTrip(req)
	if err != nil {
		log.Fatal(fmt.Sprintf("Error connecting to API: %v", err))
	}
	defer response.Body.Close()

	payload, err := ioutil.ReadAll(response.Body)
	if err != nil {
		log.Fatal(fmt.Sprintf("Unable to read API response: %v", err))
	}

	if response.StatusCode != http.StatusOK {
		log.Fatal(fmt.Sprintf("API request failed, status: %d, resp: %s", response.StatusCode, payload))
	}

	var corpResp CorpResponse
	err = json.Unmarshal(payload, &corpResp)
	if err != nil {
		log.Fatal(err)
	}

	// Print out corp data
	fmt.Printf("%+v\n", corpResp.Data)
}

Python

import requests, os

# Initial setup

endpoint = 'https://dashboard.signalsciences.net/api/v0'
email = os.environ.get('SIGSCI_EMAIL')
token = os.environ.get('SIGSCI_TOKEN')

# Fetch list of corps

headers = {
	'Content-type': 'application/json',
	'x-api-user': email,
	'x-api-token': token
}
corps = requests.get(endpoint + '/corps', headers=headers)
print corps.text

Ruby

require 'net/http'
require 'json'

# Initial setup

endpoint = "https://dashboard.signalsciences.net/api/v0"
email = ENV['SIGSCI_EMAIL']
token = ENV['SIGSCI_TOKEN']

# Fetch list of corps

corps_uri = URI(endpoint + "/corps")

http = Net::HTTP.new(corps_uri.host, corps_uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(corps_uri.request_uri)
request["x-api-user"] = email
request["x-api-token"] = token
request["Content-Type"] = "application/json"

response = http.request(request)
puts response.body

Shell

curl -H "x-api-user:$SIGSCI_EMAIL" -H "x-api-token:$ACCESS_TOKEN" -H "Content-Type: application/json" https://dashboard.signalsciences.net/api/v0/corps