Skip to main content

​
About Recorded Future

Recorded Future is a threat-intelligence platform that scores and contextualizes indicators of compromise, publishes alerts and analyst research, and tracks exposed credentials. Serval connects to the Recorded Future API at api.recordedfuture.com with a single API token, and that one connection covers the enrichment, alerting, list, analyst-note, identity, and SOAR APIs. Everything happens on demand from workflows - there is nothing to install on the Recorded Future side. Authentication: API token - you provide a Recorded Future API token, and Serval sends it in the X-RFToken header on every request it makes on your behalf. Serval only ever sends the token to api.recordedfuture.com. Adjacent Recorded Future products with separate tokens, such as the Sandbox and Attack Surface Intelligence, aren’t part of this integration. Data sync: On-demand only. There is no background sync and no entity ingestion - Serval reads and writes Recorded Future data only when a workflow runs.

​
What the Recorded Future integration enables

The integration covers a curated subset of the Recorded Future APIs - Connect enrichment and search, Alert, Playbook Alert, List, Analyst Note, Entity Match, Detection Rule, Identity, and SOAR.

​
Get your credentials

You need a Recorded Future API token. Tokens are generated in the Recorded Future portal by an Enterprise Administrator, and each token carries the API entitlements of your licensed modules - the same token works across all the APIs your subscription covers. Recorded Future’s guide is Requesting API Tokens (customer login required).
1

Log in to the Recorded Future portal

Sign in at app.recordedfuture.com with an Enterprise Administrator account.
2

Open API access

Open the menu in the upper right corner, select User Settings, then select API Access.
3

Generate the token

Select Generate New API Token, give it a descriptive name such as Serval, and choose the API services it should cover.
4

Copy the token

Copy and save the token right away.
Only Enterprise Administrators can generate API tokens. If you aren’t an administrator, ask one to generate the token for you, or submit an integration support ticket to Recorded Future specifying which API offering you need.
Endpoint access is baked into the token from your licensed modules - for example, vulnerability enrichment needs the Vulnerability Intelligence module and identity lookups need Identity Intelligence. If your organization adds a module later, regenerate the token to pick up the new entitlements.

​
Connect in Serval

1

Open the Recorded Future connection form

In Serval, add a new Recorded Future connection.
2

Enter the API Token (required)

Paste the token into the API Token password field (“Recorded Future API token, generated by an Enterprise Administrator in the Recorded Future portal under User Settings -> API Access.”). Leaving it empty shows “This field is required”.
3

Submit the form

Click Submit. If installation fails, the form shows “Failed to install integration” with details appended when available. Serval stores the token securely and attaches it to every Recorded Future request your workflows make.
When you open the connection’s settings later, the token appears masked - bullet characters plus its last 4 characters. To rotate it, replace the masked value with the complete new token and save.

​
Verifying the connection

The integration ships five built-in health checks:
  1. Test Recorded Future Connection - searches your custom lists, which every module is entitled to. Success reports “Successfully connected to the Recorded Future API”. Failure reports “Unable to connect to Recorded Future. Verify the API token is valid and hasn’t expired or been revoked.”
  2. Check Enrichment API Access - lists IP risk rules, a static metadata call with no enrichment-quota cost. Failure normally means the token’s modules don’t include SecOps, Threat, or Brand Intelligence.
  3. Check Alert API Access - fetches a single alert rule. Alerts are available on every module except SecOps Intelligence.
  4. Check Playbook Alert API Access - fetches the playbook alert category and status enumerations.
  5. Check SOAR Bulk-Enrichment Access - lists the static triage contexts. Failure normally means the token’s modules don’t include SecOps or Threat Intelligence.
Only the first check indicates a broken connection outright. If it passes while a later check fails, the token is valid but its modules don’t cover that API - the failure message names the modules that unlock it.

​
Gotchas and troubleshooting

Every Recorded Future API is gated by module entitlements that are baked into the token at generation time. A 403 with “Missing API privileges” means the token’s modules don’t cover that endpoint - it isn’t an authentication failure. If your organization licensed a new module after the token was created, regenerate the token in the Recorded Future portal.
A 401 means the token itself is invalid - expired, revoked, or mistyped. Generate a fresh token in the Recorded Future portal and update the connection.
Standard Recorded Future API subscriptions include 5,000 API calls per day across all the APIs, and bursts of traffic can return HTTP 429. For enriching many indicators, prefer one SOAR bulk-enrichment call (up to 1,000 indicators) over a loop of per-indicator lookups - it’s one call toward the quota and returns risk scores for the whole batch.
The URL enrichment endpoint takes the full URL as a path parameter. Serval URL-encodes path parameters automatically, so pass the raw URL as the id - encoding it yourself produces a double-encoded lookup that misses.
The enrichment search endpoints and classic alert search cap limit plus from at 1,000 - deeper pages aren’t reachable. Playbook alert, analyst note, and identity searches use cursor offsets instead and aren’t capped this way.
Recorded Future Sandbox (sandbox.recordedfuture.com) and Attack Surface Intelligence (served from api.securitytrails.com) use different hosts and different tokens. This integration only calls api.recordedfuture.com, so those products are out of scope.
Endpoints that return raw files - alert screenshot images, analyst-note attachments, and bulk risk-list downloads - are excluded from the endpoint catalog because Serval’s request pipeline is JSON-based. Risk data is available through the enrichment and SOAR endpoints instead.
Need help? Contact support@serval.com for assistance with your Recorded Future integration.