--- other: private: false title: Use the API --- import { Image } from "@/components/image"; import { Tabs } from "nextra/components"; # Use the API ## Things to know before using the API The [Fluid Attacks API](https://app.fluidattacks.com/api) is built as a GraphQL service where you can consume data using a common query language. [GraphQL](https://graphql.org/) provides a single endpoint [app.fluidattacks.com/api](https://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](#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](https://graphql.org/learn/). 1. **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. 1. **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](https://app.fluidattacks.com/api) following the examples below and then those in [Learn the basics of the Fluid Attacks API](https://help.fluidattacks.com/portal/en/kb/articles/learn-the-basics-of-the-fluid-attacks-api#Examples_of_a_simple_query). ### Examples #### Retrieving user role This example is to retrieve your [role](https://help.fluidattacks.com/portal/en/kb/articles/understand-roles) in the Fluid Attacks platform. Before proceeding, you should login at [app.fluidattacks.com](https://app.fluidattacks.com). ```graphql 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). ```graphql query { me { organizations { groups { name } } } } ``` ## Learn the basics of the Fluid Attacks API [Fluid Attacks](https://fluidattacks.com/)' platform allows users to make requests to its [GraphQL API](https://app.fluidattacks.com/api). Before you do that, you should have some [basic knowledge](#things-to-know-before-using-the-api) 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](http://app.fluidattacks.com/). 1. [Access the API](http://app.fluidattacks.com/api). You can go ahead and write the queries you need, and then click the play icon to execute them. Query the Fluid Attacks API

> \[!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](https://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](https://app.fluidattacks.com/). 1. Click on the [user menu](https://help.fluidattacks.com/portal/en/kb/articles/explore-the-user-menu) and select the `API token` option. Find the API Token option on the Fluid Attacks platform

Find the API Token option on the Fluid Attacks platform

1. In the pop-up window, click on `Add token`. Add API token on the Fluid Attacks platform

1. Enter a name and choose an expiration date for your token (up to six months from the current date). Generate API token on the Fluid Attacks platform

> \[!NOTE] > > Keep in mind that you can have up to two active API tokens. 1. Click on `Confirm`. The window then shows your token masked with asterisks. If you wish, you can click on `View` to reveal it. Copy API token on the Fluid Attacks platform

Copy API token on the Fluid Attacks platform

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. Get token copied message on the Fluid Attacks platform

Get token copied message on the Fluid Attacks platform

1. Enter the [GraphiQL playground](https://app.fluidattacks.com/api). 1. Select the `Headers` tab at the bottom. Authenticate to the Fluid Attacks API with token

Authenticate to the Fluid Attacks API with token

1. Under `Headers`, type `{"authorization":"Bearer YOUR_TOKEN_GOES_HERE"}`. (Replace `YOUR_TOKEN_GOES_HERE` with your actual token.) 1. 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](https://graphql.org/learn/serving-over-http/#post-request-and-body). > \[!NOTE] > > - Replace `YOUR_TOKEN_GOES_HERE` with your actual token. > - Keep your API token confidential. > Do not share it publicly or commit it to version control. > - 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](https://app.fluidattacks.com/). 1. Click on the [user menu](https://help.fluidattacks.com/portal/en/kb/articles/explore-the-user-menu) and select API token. 1. Click on `Revoke`. Revoke API token on the Fluid Attacks platform

Revoke API token on the Fluid Attacks platform

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. Revoke a valid API token on the Fluid Attacks platform

Revoke a valid API token on the Fluid Attacks platform

> \[!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. 1. 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](https://app.fluidattacks.com/api). 1. Click the book icon on the left side of the playground. Find the Fluid Attacks API documentation

Find the Fluid Attacks API documentation

1. Browse through the available queries, mutations, and schema types. Browse the Fluid Attacks API documentation

> \[!NOTE] > > Learn about [data model information](https://help.fluidattacks.com/portal/en/kb/articles/data-model) > available through the API. ### 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. Get non paginated lists on the Fluid Attacks API

Get non paginated lists on the Fluid Attacks API

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. See paginated fields on the Fluid Attacks API

See paginated fields on the Fluid Attacks API

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](https://graphql.org/learn/pagination/) 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. Retrieve vulnerabilities on the Fluid Attacks API

Retrieve vulnerabilities on the Fluid Attacks API

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. Get cursor on the Fluid Attacks API

To see the next page, you can pass the cursor token as the argument `after` in your next query. Use the after argument on the Fluid Attacks API

Continue making requests with the updated `after` argument until `hasNextPage` is false, indicating that you have retrieved all pages. See [other examples](https://graphql.org/learn/pagination/#complete-connection-model) in the GraphQL documentation. ### Rate limits The [Fluid Attacks API](https://app.fluidattacks.com/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: ```python 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](https://app.fluidattacks.com/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. ```python 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: | Status code | Description | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | **OK**: The request has been processed. You can learn more about the structure of the [response body](https://graphql.org/learn/serving-over-http/#response-format) in the GraphQL documentation. | | 400 | **Bad Request**: The request has a syntax error or is malformed. Check the response body for details about the error. Refer to the GraphQL documentation for guidance on [proper query syntax](https://graphql.org/learn/). | | 429 | **Too Many Requests**: You have exceeded the API rate limit (100 requests per minute). Reduce the frequency of your requests or implement a retry mechanism with exponential backoff, respecting the retry-after header value (in seconds) provided in the response. | | 502-504 | **Bad Gateway / Gateway Timeout**: These errors usually indicate temporary server issues or network problems. Implement a retry mechanism in your code. If the errors persist, please contact [help@fluidattacks.com](mailto:help@fluidattacks.com). | ### 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.