Using the Next-Gen WAF API

IMPORTANT

This guide only applies to Next-Gen WAF customers with access to the Next-Gen WAF control panel. If you have access to the Next-Gen WAF product in the Fastly control panel, check out the Fastly Security API.

Our entire control panel is built API-first — this means that anything we can do, you can do as well via our RESTful/JSON API.

We’ve seen customers use our API a number of ways, but a common use case is importing our request data into a security information and event management (SIEM) solution (e.g., Datadog, Kibana, and Sumo Logic). With a SIEM, you can correlate your internal data with data from the Next-Gen WAF.

TIP

We offer a Terraform provider.

About API access tokens

Anyone with the appropriate permissions 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, everyone has the ability to create and use API access tokens. However, owners can choose to restrict API Access Token creation and usage to specific people. All plans allow you to create up to 5 access tokens per person.

Managing API access tokens

Follow these steps when managing API access tokens.

Creating API access tokens

  1. Log in to the Next-Gen WAF control panel.
  2. From the My Profile menu, select API access tokens.

  3. Click Add API access token.

  4. In the Token name field, enter a name to identify the access token.

    IMPORTANT

    Don't use special characters (e.g., -, @, !, or %) in token names. These often result in a 400 Bad Request HTTP status code error being sent.

  5. Click Create API access token.

  6. Record the token in a secure location for your use.

    IMPORTANT

    This is the only time the token will be visible. Record the token and keep it secure. For your security, it will not appear in the control panel.

  7. Click Continue to finish creating the token.

Restricting permission to create and use API access tokens

Owners can restrict the creation and use of API access tokens. After doing so, Owners can then manually grant a specific person 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 control panel will remember that permission moving forward.

Owners can enable API Access Token restrictions by following these steps:

  1. Log in to the Next-Gen WAF control panel.
  2. From the Corp Manage menu, select User Authentication.
  3. Navigate to the API access tokens section.
  4. In the Access token permissions field, select the Restrict access by user option. A message will be displayed warning you about this setting and its restrictions.
  5. Click Continue to proceed.
  6. Click Update API access tokens to save this change.

Granting permission to create and use API access tokens

When API access token creation and usage is restricted, only owners can enable other users to create API access tokens.

NOTE

After restricting API Access Token usage, Owners will also need to grant themselves permission to create and use API access tokens.

  1. Log in to the Next-Gen WAF control panel.
  2. From the Corp Manage menu, select Corp Users.
  3. Click on the user you want to grant permission to.
  4. Click Edit corp user.
  5. Under the Authentication section, select the Allow this user to create API access tokens checkbox.
  6. Click Update user.

Deleting API access tokens

  1. Log in to the Next-Gen WAF control panel.
  2. From the My Profile menu, select API access tokens.
  3. Click Delete to the right of the token you want to delete.
  4. Click Delete to confirm you want to delete the token.

Viewing Personal API Tokens

Owners can view a table of all access tokens across your corp by going to the Corp Manage menu and selecting 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 Corporation-Wide API Access Token Settings

Follow these steps when managing corporation-wide API access token settings.

Setting Automatic Token Expirations

Owners can set API access tokens to automatically expire after a set period of time.

  1. Log in to the Next-Gen WAF control panel.
  2. From the Corp Manage menu, select User Authentication.

  3. Navigate to the API access tokens section.

  4. In the Access token expiration, select the Custom expiration option.

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

  6. Click Update API access tokens.

Restricting API Access Token Usage by IP

Owners can restrict the use of API access tokens to specific IP addresses.

  1. Log in to the Next-Gen WAF control panel.
  2. From the Corp Manage menu, select User Authentication.
  3. Navigate to the API access tokens section.
  4. In the Restrict usage by IP (optional) field, enter the IP addresses and IP ranges you want to limit token usage to. Enter each IP address on a new line.
  5. Click Update API access tokens.

Using Personal API access tokens

Golang

1package main
2
3import (
4 "encoding/json"
5 "fmt"
6 "io/ioutil"
7 "log"
8 "net/http"
9 "os"
10 "time"
11)
12
13var (
14 // Defines the API endpoint
15 endpoint = "https://dashboard.signalsciences.net/api/v0"
16 email = os.Getenv("SIGSCI_EMAIL")
17 token = os.Getenv("SIGSCI_TOKEN")
18)
19
20// Corp is a Signal Sciences corp (also known as account)
21type Corp struct {
22 Name string
23 DisplayName string
24 SmallIconURI string
25 Created time.Time
26 SiteLimit int
27 Sites struct {
28 URI string
29 }
30 AuthType string
31 MFAEncorced bool
32}
33
34// CorpResponse is the response from the Signal Sciences API
35// containing the corp (account) data.
36type CorpResponse struct {
37 Data []Corp
38}
39
40func main() {
41 // No need for timestamps or anything
42 log.SetFlags(0)
43
44 // Get corps
45 req, err := http.NewRequest("GET", endpoint+"/corps", nil)
46 if err != nil {
47 log.Fatal(err)
48 }
49
50 // Set headers
51 req.Header.Set("x-api-user", email)
52 req.Header.Set("x-api-token", token)
53 req.Header.Set("Content-Type", "application/json")
54 req.Header.Add("User-Agent", "SigSci Go-Example")
55
56 // Make request
57 var transport http.RoundTripper = &http.Transport{}
58 response, err := transport.RoundTrip(req)
59 if err != nil {
60 log.Fatal(fmt.Sprintf("Error connecting to API: %v", err))
61 }
62 defer response.Body.Close()
63
64 payload, err := ioutil.ReadAll(response.Body)
65 if err != nil {
66 log.Fatal(fmt.Sprintf("Unable to read API response: %v", err))
67 }
68
69 if response.StatusCode != http.StatusOK {
70 log.Fatal(fmt.Sprintf("API request failed, status: %d, resp: %s", response.StatusCode, payload))
71 }
72
73 var corpResp CorpResponse
74 err = json.Unmarshal(payload, &corpResp)
75 if err != nil {
76 log.Fatal(err)
77 }
78
79 // Print out corp (account) data
80 fmt.Printf("%+v\n", corpResp.Data)
81}

Python

1import requests, os
2
3# Initial setup
4
5endpoint = 'https://dashboard.signalsciences.net/api/v0'
6email = os.environ.get('SIGSCI_EMAIL')
7token = os.environ.get('SIGSCI_TOKEN')
8
9# Fetch list of corps (accounts)
10
11headers = {
12 'Content-type': 'application/json',
13 'x-api-user': email,
14 'x-api-token': token
15}
16corps = requests.get(endpoint + '/corps', headers=headers)
17print corps.text

Ruby

1require 'net/http'
2require 'json'
3
4# Initial setup
5
6endpoint = "https://dashboard.signalsciences.net/api/v0"
7email = ENV['SIGSCI_EMAIL']
8token = ENV['SIGSCI_TOKEN']
9
10# Fetch list of corps (accounts)
11
12corps_uri = URI(endpoint + "/corps")
13
14http = Net::HTTP.new(corps_uri.host, corps_uri.port)
15http.use_ssl = true
16
17request = Net::HTTP::Get.new(corps_uri.request_uri)
18request["x-api-user"] = email
19request["x-api-token"] = token
20request["Content-Type"] = "application/json"
21
22response = http.request(request)
23puts 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
Was this guide helpful?

Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.