Skip to main content
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 or European Union portal.
  • 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 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.