Use the API

Things to know before using the API

The Fluid Attacks API  is built as a GraphQL service where you can consume data using a common query language. GraphQL  provides a single endpoint app.fluidattacks.com/api  for making requests using queries (to fetch data) and mutations (to create, update, or delete data). If you are already familiar with GraphQL, feel free to jump ahead to Learn the basics of the Fluid Attacks API.

Recommendations for new GraphQL users

Here are some recommendations for developers unfamiliar with GraphQL:

1. Understand what GraphQL is: Gain foundational knowledge of GraphQL, including its functionalities and how to construct queries for a GraphQL endpoint. It is advisable to refer to the official GraphQL introduction .
2. Learn to make queries and mutations: Before diving into the API, grasp the concepts of queries and mutations as they form the core operations over any GraphQL endpoint.
3. Explore the Fluid Attacks API with the help of this Knowledge Base: Once you have grasped basic GraphQL concepts (queries, mutations, fields, and arguments), proceed to explore the API at app.fluidattacks.com/api  following the examples below and then those in Learn the basics of the Fluid Attacks API .

Examples

Retrieving user role

This example is to retrieve your role  in the Fluid Attacks platform. Before proceeding, you should login at app.fluidattacks.com .

query {
  me {
    role
  }
}

Retrieving groups

This example enhances the previous query to retrieve information about your groups. Since groups are a list of projects (which are GraphQL entities), you must specify the desired information from them (in this case, their names).

query {
  me {
    organizations {
      groups {
        name
      }
    }
  }
}

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

   

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

   

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

   
   Note

   Keep in mind that you can have up to two active API tokens.

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

   

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

   

7. Enter the GraphiQL playground .

8. Select the Headers tab at the bottom.

   

9. Under Headers, type {"authorization":"Bearer YOUR_TOKEN_GOES_HERE"}. (Replace YOUR_TOKEN_GOES_HERE with your actual token.)

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

import requests
query = """
{
  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())

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());

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.

   
   Caution

   Once you revoke a token, even if it had not expired, it becomes invalid and cannot be used for authentication. Any integrations using the revoked token will require a new one to resume their functioning.

4. Click on Confirm.

Access playground docs

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

1. Go to the app.fluidattacks.com .

2. Click the book icon on the left side of the playground.

   

3. 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 requests
from time import sleep
query = """
{
  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 response
response = 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 = 10
 
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)
        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 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.