> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NodeZero

> Connect Horizon3.ai NodeZero to read pentest data in workflows with automatic access-token renewal.

Serval connects to NodeZero using an API key from the Horizon3.ai portal. It exchanges the stored key for a short-lived JWT and renews the token before it expires. Workflow authors never handle the API key or JWT.

## Before you connect

* Create a NodeZero API key in the [United States portal](https://portal.horizon3ai.com) or [European Union portal](https://portal.horizon3ai.eu).
* Use an account with the permissions your workflows need. The integration acts with the API key's permissions.
* Note your account's region. Serval supports the United States and European Union APIs.

## Connect NodeZero

**1. Open the integration**

Go to **Integrations → Connect new**, search for **NodeZero**, and select **Connect**.

**2. Enter your credentials**

Select the **API region** that matches your NodeZero account and paste your **API key**. Use the API key, rather than an access token copied from an authentication response.

**3. Connect and test**

Submit the form and run **Test NodeZero Connection**. The check exchanges the key for a token and makes a read-only GraphQL request. **Read NodeZero Pentest Count** and **Read NodeZero Pentests** check access to pentest data without starting a pentest.

## Use NodeZero in workflows

The integration provides three read actions:

* **Count NodeZero pentests** returns the pentest count. Provide an optional `page_input` to filter the count.
* **List NodeZero pentests** returns pentest summaries. Use `page_input` to set `page_num`, `page_size`, and `filter_by_inputs`.
* **Get NodeZero pentest** returns a pentest summary for an `op_id`, or `null` when no matching pentest is available.

Each action uses a fixed GraphQL query. Workflow inputs supply variables, and Serval supplies authentication and the regional endpoint. These actions cannot start pentests or run arbitrary GraphQL operations.

GraphQL errors fail the action even when NodeZero returns HTTP 200. See the [Horizon3.ai GraphQL reference](https://docs.horizon3.ai/api/graphql/) for pagination and filter fields.

## Authentication and troubleshooting

* **Automatic renewal:** NodeZero JWTs expire after one hour. Serval caches tokens per connection and obtains a new token five minutes before expiry when the connection is used. Renewal also respects an earlier expiry reported by the JWT.
* **Invalid credentials:** Verify that you entered an API key and selected the correct region. A revoked or expired API key must be replaced in the integration settings.
* **Editing credentials:** Leaving the API key unchanged preserves the encrypted stored value. Replace it to rotate the credential. To use a different API region, create a new NodeZero connection and select it in your workflows.
* **Permission errors:** Check the API key's permissions in NodeZero. Reconnecting cannot grant permissions the key does not have.
* **Existing custom workflows:** Select the native NodeZero connection and use the matching pentest read action. Existing custom applications and workflows are not converted automatically.

Serval calls `api.gateway.horizon3ai.com` for the United States and `api.gateway.horizon3ai.eu` for the European Union. The key exchange runs behind the integration proxy; credentials are not included in workflow inputs or outputs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.