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

# Assetnote

> Assetnote is an attack surface management platform - connect it to Serval so workflows can read your assets, exposures, technologies and vulnerabilities.

## About Assetnote

Assetnote, from Searchlight Cyber, continuously discovers your internet-facing assets and tests them for exposures. Connecting it to Serval lets workflows read assets, exposures, technologies, vulnerabilities, asset groups and summary statistics.

**Authentication:** Machine token. You enter your Assetnote instance's host and a machine token created in Assetnote. Serval stores the token server-side and attaches it to requests for you - it is never exposed to workflow code, and it is only ever sent to the instance you entered.

**Data sync:** On demand. There is no background sync - workflows, actions and health checks call the Assetnote API at the moment they run.

**Read only:** Serval sends only GraphQL queries to Assetnote. It refuses mutations and subscriptions, and refuses queries that select credentials Assetnote stores for other services.

## What the Assetnote integration enables

| Capability | Description |
| - | - |
| Assetnote API access | The built-in "Assetnote API request" action sends a GraphQL query to your instance's `/api/v2/graphql` endpoint. |
| Assets | List and look up subdomain, IP and cloud assets, with filtering, sorting and paging. |
| Exposures | Read exposures and exposure events found on your attack surface. |
| Technologies and vulnerabilities | Read the technologies detected on your assets and the vulnerabilities that affect them. |
| Asset groups and statistics | Read asset groups and the asset and exposure overview statistics. |
| Health checks | Three built-in health checks validate the connection and read access to assets and exposures. |

## Get your credentials

**1. Find your instance domain**

Your instance domain is the host you use to sign in to Assetnote, such as `yourcompany.assetnotecloud.com`.

**2. Create a machine token**

In Assetnote, create a machine token for Serval with the **Read-only** role. If you can't create machine tokens, ask your Assetnote administrator or Assetnote support.

**3. Copy the token**

Copy the token and keep it somewhere safe until you've pasted it into Serval.

## Connect in Serval

**1. Instance domain (required)**

Enter the host of your Assetnote instance, for example `yourcompany.assetnotecloud.com`, without `https://`.

**2. Machine token (required)**

Paste the machine token. Once saved, it displays masked.

**3. Save and verify**

Save the connection, then run the health checks below.

> [!NOTE]
>
> To move a connection to a different instance domain, enter the machine token again. A token created for one instance does not work on another.

## Verifying the connection

**Validate Assetnote API connection** - verifies the token can reach the Assetnote GraphQL API and reports the token's role.

* Success: "Successfully connected to Assetnote (role: \[role])."
* Failure: "Unable to connect to the Assetnote API. Verify that the machine token is valid and the instance domain is correct."

**List assets in Assetnote** - verifies the token can read assets by counting them.

* Success: "Successfully read assets from Assetnote (\[number] total)."

**List exposures in Assetnote** - verifies the token can read exposures by counting them.

* Success: "Successfully read exposures from Assetnote (\[number] total)."

## Gotchas and troubleshooting

> [accordion] A request fails with "Assetnote request refused"
>
> Serval refused the request before it reached Assetnote. The message says why: the document contains a mutation or subscription, or it selects a field that returns a stored credential (such as `apiKey`, `apiToken` or `awsSecretAccessKey`). Remove that part of the query.

> [accordion] The instance domain is rejected
>
> Serval accepts only a single host under `assetnotecloud.com`, such as `yourcompany.assetnotecloud.com`. Remove any `https://`, path or port.

> [accordion] It's a GraphQL-only API
>
> Assetnote exposes one GraphQL endpoint, so workflows reach everything through the "Assetnote API request" action. If Assetnote reports errors, the action fails with "Assetnote GraphQL request returned errors:" followed by each error message.

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Assetnote integration.


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