Learn the basics of the Fluid Attacks API

Fluid Attacks ’ platform allows users to make requests to its GraphQL API . Before you do that, you should have some basic  knowledge  of this query language. Once familiarized, you can follow this guide, which walks you through the authentication process and show you how to start exploring the API.

Authenticate to use the API

You can authenticate to the Fluid Attacks API from the GraphiQL playground or by HTTP requests in code. This guide explains two possible ways of authentication through the GraphiQL playground.

Authentication with Fluid Attacks’ platform login

You can choose to authenticate through Fluid Attacks’ platform login:

1. Log in to the platform .
2. Access the API .

You can go ahead and write the queries you need, and then click the play icon to execute them.

Authentication with Fluid Attacks’ platform API token

You can authenticate to Fluid Attacks’ API with a token, which you have to generate on the platform. The steps are explained below.

1. Log in to Fluid Attacks’ platform at app.fluidattacks.com .
2. Click on the user menu  and select the API token option.

1. In the pop-up window, click on Add token.

1. Enter a name and choose an expiration date for your token (up to six months from the current date).

1. Click on Confirm. The window then shows your token masked with asterisks. If you wish, you can click on View to reveal it.

1. Click on Copy and store this token safely, as the platform will not show it to you ever again after you close the pop-up window. The platform displays a message briefly when the token is copied successfully.

1. Enter the GraphiQL playground .
2. Select the Headers tab at the bottom.

1. Under Headers, type \{"authorization":"Bearer YOUR_TOKEN_GOES_HERE"\}. (Replace YOUR_TOKEN_GOES_HERE with your actual token.)
2. Write your GraphQL queries in the upper area and click on the play icon to execute them.

Examples of a simple query

Here are examples of how to make a simple query to the Fluid Attacks API using Python, JavaScript, and Bash. This query retrieves the current user’s username and email. All examples use the POST method to send the GraphQL query to the API endpoint. You can learn about this method reading the official GraphQL documentation .

Python

import requestsquery = """{  me {    userName    userEmail  }}"""token = "YOUR_TOKEN_GOES_HERE"response = requests.post(  "https://app.fluidattacks.com/api",  json={"query": query},  headers={"authorization": f"Bearer {token}"},)print(response.json())

JavaScript

const response = await fetch("https://app.fluidattacks.com/api", {  headers: {    "content-type": "application/json",    authorization: "Bearer YOUR_TOKEN_GOES_HERE",  },  body: JSON.stringify({ query: "{ me { userName userEmail }}" }),  method: "POST",});console.log(await response.json());

Bash

curl \  --request POST \  --url https://app.fluidattacks.com/api \  --header "content-type: application/json" \  --header "authorization: Bearer YOUR_TOKEN_GOES_HERE" \  --data '{"query": "{ me { userName userEmail }}"}'

Revoke API token

You might need to revoke an API token if it has expired or you have lost it. Follow these steps to revoke the token:

1. Log in to the Fluid Attacks platform at app.fluidattacks.com .
2. Click on the user menu  and select API token.
3. Click on Revoke.

If you are revoking a valid token that you have used within the past seven days, you receive a warning message showing the last time it was used.

1. Click on Confirm.

Access playground docs

The GraphiQL playground provides built-in documentation to help you explore the API:

1. Go to the API page .
2. Click the book icon on the left side of the playground.

1. Browse through the available queries, mutations, and schema types.

Paginated fields

The Fluid Attacks API uses both paginated and non-paginated lists. Non-paginated lists return all available results directly, as a normal list, and between square brackets. An example is shown in the screenshot below.

Paginated lists, often identified by the suffix Connection, return only a certain amount of results and a “cursor” that can be included in subsequent requests to advance through the pages.

It is important to keep these differences in mind when building integrations that need to retrieve all the information in a paginated field. Read the GraphQL’s official pagination documentation  for more information.

Consider this example to better understand pagination: Retrieving the first ten vulnerabilities of a group named Narrabri. The query is shown in the screenshot below.

Explore the terminal. If there is a next page in the last item of the query, you can see hasNextPage and endCursor, where the former informs there is a next page and the latter provides its cursor token.

To see the next page, you can pass the cursor token as the argument after in your next query.

Continue making requests with the updated after argument until hasNextPage is false, indicating that you have retrieved all pages. See other examples  in the GraphQL documentation.

Rate limits

The Fluid Attacks API  has a rate limit of 100 requests per minute. If you exceed this limit, you receive an HTTP 429 (Too Many Requests) error response. The response includes a retry-after header indicating how long to wait before making another request.

See how to control this scenario with a Python script:

import requestsfrom time import sleepquery = """{  me {    userName    userEmail  }}"""token = ""def request():    while True:        response = requests.post(            "https://app.fluidattacks.com/api",            json={"query": query},            headers={"authorization": f"Bearer {token}"},        )        if response.status_code == 429:            seconds = response.headers["retry-after"]            sleep(seconds + 1)        else:            break    return responseresponse = request()print(response.json())

This solution may vary depending on the HTTP client library or language of your preference. Waiting 1 additional second to the value indicated by the header is also advisable.

Temporary network errors

The Fluid Attacks API  may occasionally experience temporary network issues, such as timeouts due to high demand or connection failures.

To make your integration more resilient, implement a retry mechanism for failed requests. This is especially crucial for mission-critical processes that rely on the API. The following is a small example in a Python script.

MAX_RETRIES = 10def request():    while True:        response = requests.post(            "https://app.fluidattacks.com/api",            json={"query": query},            headers={"authorization": f"Bearer {token}"},        )        if response.status_code == 429:            seconds = response.headers["retry-after"]            sleep(seconds + 1)        elif response.status >= 500:            retries += 1            if retries == MAX_RETRIES:                break            sleep(retries)        else:            break    return response

Remember that the above solution may vary depending on the HTTP client library or language of your preference.

Fluid Attacks’ platform API response status

The Fluid Attacks platform API uses standard HTTP status codes to indicate the success or failure of your requests. Here are some of the most common codes you might encounter:

Response times

With GraphQL you can request a large amount of data in a single request, but you have to keep in mind that the response times will vary accordingly. Therefore, it may be useful to split queries into different requests as needed.