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 at app.fluidattacks.com.


2. Access the API at app.fluidattacks.com/api.

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

Note: This method uses the same session as the platform, which lasts for 40 minutes. After that, you need to log in at app.fluidattacks.com again and refresh the API page. If you want your session to last more than 40 minutes, you can use an API token as shown below.

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 at app.fluidattacks.com/api.


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.

Notes:

1. Replace YOUR_TOKEN_GOES_HERE with your actual token.
   
2. Keep your API token confidential. Do not share it publicly or commit it to version control.
   
3. When you run the script, you get what you requested from the query in the terminal.
   

Python

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

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.





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 app.fluidattacks.com/api.
   


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 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:

Free trial

Search for vulnerabilities in your apps for free with Fluid Attacks' automated security testing! Start your 21-day free trial and discover the benefits of the Continuous Hacking Essential plan. If you prefer the Advanced plan, which includes the expertise of Fluid Attacks' hacking team, fill out this contact form.