API access

DFIRe provides a full REST API for programmatic access. Use API keys to authenticate SIEM connectors, SOAR playbooks, custom scripts, and third-party integrations.

Overview

Every action available in the DFIRe web interface is also available through the REST API. A few actions on your own account and your own keys need a signed-in browser session, and DFIRe refuses them through an API key. See Actions that need a browser session. API keys allow external systems to authenticate and perform operations with the same permission model as browser-based users.

Key concepts:

  • API Keys are per-user Bearer tokens that inherit the user's full RBAC permissions
  • Service Accounts are dedicated user accounts that authenticate exclusively via API key (no password or SSO login)
  • API Documentation is built into every DFIRe installation as an interactive reference at /api/docs/

API Keys

API keys provide programmatic access to DFIRe. Each key is tied to a specific user and inherits that user's group memberships, permissions, and case access. Any endpoint accessible via the browser is accessible via API key with the same authorization checks, except the actions that need a browser session.

Creating an API Key

  1. Open API Keys from the profile menu

    Click your avatar in the header and choose API Keys. Any authenticated user can create API keys for their own account.

  2. Click "Create API Key"

    Provide a descriptive name (e.g., "Splunk SOAR connector") and set an expiration date. The expiration cannot exceed the tenant-configured maximum lifetime.

  3. Copy the raw key immediately

    The full key (starting with dfire_ak_) is displayed only once. Store it securely. DFIRe stores only a SHA-256 hash and cannot recover the original key.

Important: The raw API key is shown only at creation time and after regeneration. If you lose it, you must regenerate the key (which invalidates the old one).

Key Properties

Property Description
Name A descriptive label for identifying the key's purpose.
Description Optional notes about what system uses this key.
Expiration Mandatory. Keys automatically stop working after this date. Bounded by the tenant maximum lifetime setting.
Enabled Keys can be temporarily disabled without deletion. Disabled keys reject all requests. Turning a key back on needs core.change_userapikey or superuser status, and a signed-in browser session in both cases.
Key Prefix The first 12 characters of the key (e.g., dfire_ak_a1b2), visible in audit logs for identification.

Managing API Keys

In the same API Keys view you can:

  • Disable / Enable. Disabling suspends a key without deleting it. Enabling it again needs core.change_userapikey or superuser status, and a signed-in browser session in both cases.
  • Regenerate. Create a new key value (the old value stops working immediately). An expired key cannot be regenerated, because the new value would keep the same past expiry. Extend the expiration first, or delete the key and create a new one.
  • Delete. Permanently remove a key
  • View usage. See last used timestamp, IP address, and total request count

Tenant Policy

Administrators can configure API key policy in Settings > Global Settings:

Setting Default Description
Maximum keys per user 3 Limits the number of active (enabled and non-expired) keys a single user can have.
Maximum key lifetime 365 days The furthest expiration date allowed, counted from today, when you create a key or change its expiration.

Admin Key Management

Only a superuser manages another account's API keys, whatever permissions a role holds. In Settings → User Accounts, a superuser edits the user to list, issue, edit, disable, re-enable, regenerate and delete their keys. Through the API, the same routes take the user_id parameter. Issuing, extending and re-enabling a key need a signed-in browser session, a superuser's included (see Actions that need a browser session). So a superuser issues, extends and re-enables a service account's keys from the browser. For everyone else, the API keys section of a user appears only on their own account.

A key authenticates as its account and carries that account's permissions, so issuing one lends out the account. core.change_userapikey gives no access to other accounts' keys. It lets its holder re-enable their own disabled key, from a signed-in browser session.

Password change revocation: When an administrator changes another user's password, all of that user's enabled API keys are automatically disabled as a security measure. To use a key again, the user re-enables it from a signed-in browser session, which needs core.change_userapikey. A superuser can also re-enable it, or the user creates a new key. Changing your own password does not affect your keys.

Service Accounts

Service accounts are dedicated user accounts designed for automated systems. They authenticate exclusively via API key. Password login and SSO are blocked. A System Root account cannot become a service account.

Creating a Service Account

  1. Create a new user account

    Go to Settings → User Accounts and create a regular user account (for example svc-splunk).

  2. Enable the service account flag

    In the user's profile, check "Service Account". This blocks password and SSO login. The user pickers, such as the ones for the lead and the team, offer the account only to people who may change user accounts. The Lead filter of the case lists offers it to every user while the account is active.

  3. Assign appropriate roles

    Give the service account the roles that grant the permissions it needs. Follow the principle of least privilege.

  4. Create an API key

    A superuser edits the service account in Settings → User Accounts and creates the key from its API Keys section.

Making an account a service account is permanent, and it signs the account out everywhere. Only a System Root user can turn the setting back off. The change ends every open browser session immediately and deletes every API key the account holds, so anyone signed in is returned to the login screen and anything authenticating with a key stops working straight away. Afterwards, a superuser issues a new key from a signed-in browser session, and the integrations that used the old key need it.

The setting is one-way for user administrators because it takes password and SSO sign-in away from the account. A converted account stays converted and can no longer sign in with a password or SSO, so the change is immediately visible to the person who uses it. Every conversion is recorded in the audit log against the account, whoever made it, and the API key they used if they worked through the API.

Custom Permissions via Roles

API keys inherit all permissions from the user account they belong to, including its roles. To grant a service account (or any API key holder) a custom set of permissions, create a dedicated role in Settings → Access Roles and grant it only the capabilities that integration needs, then assign the role to the account. This lets you enforce least privilege: a SIEM connector role might hold only view capabilities on cases and indicators, while a SOAR playbook role could additionally hold create and edit capabilities on cases. See Users and roles → Editing roles.

Audit trail: All actions performed via API key are logged with the key prefix (e.g., dfire_ak_a1b2...) in the audit log, making it easy to trace which integration performed each action.

Authentication

API requests are authenticated using the Authorization header with a Bearer token:

Authorization: Bearer dfire_ak_your_key_here

Example: List Cases

curl -H "Authorization: Bearer dfire_ak_abc123..." \
     https://your-dfire-instance.com/api/cases/

Each entry in the case list carries the first 300 characters of the description. To read the whole description, get the case: GET /api/cases/{id}/.

Example: Create a Case

curl -X POST \
     -H "Authorization: Bearer dfire_ak_abc123..." \
     -H "Content-Type: application/json" \
     -d '{"title": "Phishing incident", "case_mode": "incident", "severity": "high"}' \
     https://your-dfire-instance.com/api/cases/

Setting case attributes

The attributes field holds the values of the playbook's custom fields. Send it as one JSON object. Each key is the field's Database key from the playbook's Custom Fields, not the label the case shows. Choose the playbook with case_type, which takes the playbook's ID (see Looking up record IDs).

curl -X POST \
     -H "Authorization: Bearer dfire_ak_abc123..." \
     -H "Content-Type: application/json" \
     -d '{"title": "Wazuh alert 5712", "case_type": 4, "severity": "medium",
          "external_id": "WAZUH-5712",
          "attributes": {"wazuh_agent": "agent-01", "rule_level": "12",
                         "personal_data_involved": false, "first_seen": "2026-10-15"}}' \
     https://your-dfire-instance.com/api/cases/

Send a text field as a string, a Yes/No field as true or false, and a date as a YYYY-MM-DD string. The web app saves a number field as a string, so send numbers as strings to match the values people enter.

DFIRe stores the object as you send it. It does not check the keys or the value types against the playbook, and it does not enforce required fields. It refuses a value that is not a JSON object with status 400. That includes a string, a list, and a JSON object sent inside a string. A PATCH that carries attributes replaces the whole object, so send every value you want to keep. A PATCH without attributes leaves them unchanged.

Creating a case with evidence and timeline events

An integration can send a case and what belongs to it in one request. Add items, a list of evidence items, and timeline_events, a list of manual timeline events. Each entry takes the fields of POST /api/items/ without case, or of POST /api/cases/{id}/timeline/. Send at most 100 entries in each list. A list that is null or empty adds nothing, and the request works as a plain create. An item entry can set category to asset and give an external_reference, such as the hostname of the endpoint that raised the alert. See Evidence and assets.

curl -X POST \
     -H "Authorization: Bearer dfire_ak_abc123..." \
     -H "Content-Type: application/json" \
     -d '{"title": "Wazuh alert 5712", "case_type": 4, "lead_investigator": 12,
          "items": [{"item_type": 3, "name": "web-01 auth.log"}],
          "timeline_events": [{"subject": "Alert received from Wazuh",
                               "event_datetime": "2026-11-08T10:00:00Z"}]}' \
     https://your-dfire-instance.com/api/cases/

DFIRe stores the case and every entry together. The response is the new case with item_ids and timeline_event_ids added. Each entry needs the permission its own request needs on the new case, for example core.add_item for evidence. DFIRe checks those permissions first: without one, the response is status 403 and names the list, before DFIRe checks the case or compares it with open cases. If an entry is invalid, the response is status 400 and names the list and the entry's position, for example items entry 0. In both cases DFIRe stores nothing. A case that a drop rule refuses or that deduplication adds to an open case stores no entries. An automation rule that closes a new case runs after the entries are stored. A request without the two lists works as before. The MCP tool create_case takes the same two lists.

Authentication Behavior

Scenario Result
Valid, enabled, non-expired key Request proceeds with the key owner's permissions
Expired key 401 Unauthorized
Disabled key 401 Unauthorized
Invalid key value 401 Unauthorized
Key owner's account is inactive 401 Unauthorized
Invalid key after too many failed attempts from the same IP 429 Too Many Requests with Retry-After
Too many requests with a key or token in progress at the same time 429 Too Many Requests with Retry-After (see When the server is busy)
No Authorization header Falls through to session auth (browser login)
Failed attempts: After 10 failed attempts from one IP address within 5 minutes, DFIRe refuses further invalid keys from that address for 10 minutes with 429. During that time it writes no audit entry for them. A valid key from the same address keeps working, and a successful authentication resets the counter.

When the server is busy

DFIRe works on at most 16 requests with an API key or token at the same time. API keys, Dashboard Sync tokens and TAXII keys all count. DFIRe answers a further request at once with 429 Too Many Requests and the header Retry-After: 10, and does not run it. Wait the number of seconds in Retry-After, then send the request again.

An integration can send many requests at once, for example a SIEM during an alert storm. It must queue them and retry each one that gets 429. A refused request changes nothing in DFIRe, so an integration that drops it loses that data. Requests from the web app do not count toward the limit, so people keep working.

Multi-Factor Authentication and API keys

An API key is a credential in its own right. DFIRe never asks it for a code, whether or not its owner has multi-factor authentication turned on. Treat a key as equal to the account it belongs to: give it an expiry, keep it out of shared storage, and disable it once it is no longer needed.

A key cannot set up, change or remove multi-factor authentication. DFIRe refuses those requests unless they come from a signed-in browser session. A key that could also enrol an authenticator would turn a leaked key into permanent control of the account.

Administering other people's accounts is different, and a key with the permission to change users can do it. That includes clearing a user's multi-factor authentication and restoring the sign-ins a tenant-wide requirement has used up.

Actions that need a browser session

The following actions need a signed-in browser session. Through an API key they answer 403 with {"detail": "This action needs a signed-in browser session. An API key cannot perform it."}, also with a superuser's key.

  • Issuing an API key (POST /api/api-keys/)
  • Extending a key's expiry, to a later date or to no expiry
  • Re-enabling a disabled key
  • Changing your password (/api/change-password/)
  • Ending your sessions (/api/my-sessions/<id>/revoke/ and /api/my-sessions/revoke-others/)
  • Setting the password of your own account, ending its sessions or resetting its multi-factor authentication through the user administration routes

Through a key, an account can list, rename, disable, delete and regenerate its own keys, and shorten their expiry. A leaked key therefore cannot issue new keys or bring back a disabled one.

API Documentation

Every DFIRe installation includes built-in API reference documentation generated from the live application. The documentation is always up-to-date and reflects the exact endpoints, parameters, and response formats available in your version.

Accessing the API Reference

Resource URL Description
API Reference /api/docs/ Interactive ReDoc documentation with endpoint descriptions, request/response schemas, and authentication details.
OpenAPI Schema /api/docs/schema/ Raw OpenAPI 3.0 YAML schema. Import into Postman, Insomnia, or code generators.

Both endpoints require authentication (browser session or API key). Links are also available in Settings > Global Settings under the API Documentation section.

The API reference works without internet access. Its script is included in DFIRe, and it uses system fonts.

Looking up record IDs

Many API fields take the ID of another record. For example, lead_investigator takes a user ID and case_type takes a playbook ID. The interface shows these records by name only, so a superuser finds their IDs in Settings → Integration IDs.

  1. Select a record type

    Choose it under Record type, for example User accounts or Playbooks.

  2. Find the record

    Search by name or by ID. User accounts also match on the username.

  3. Copy the ID

    Click the ID to copy it to the clipboard.

Above the list, the tab names the endpoints and fields that take the ID. Each field shows the format it expects: 1 for a single ID, [1] or [1, 2] for a list. The list includes deactivated accounts and inactive projects, marked Inactive, because existing records can still refer to them.

Record types: user accounts, playbooks, item types, workflow steps of the evidence and asset workflows, triage flags, incident phases, incident categories, outcome verdicts, projects, access roles and legal entities.

Key Endpoint Groups

The API is organized into the following groups:

Group Base Path Description
Cases /api/cases/ Case CRUD, bulk update, timers, indicators, timeline, exports, tag suggestions
Items /api/items/ Evidence item management. Without case, the list returns every item you can see, with its case in case_details
Attachments /api/attachments/ Encrypted file uploads and downloads
IOC /api/indicators/ Indicator registry, enrichment, bulk operations, tag suggestions
API Keys /api/api-keys/ API key management
Users /api/users/ User management and profiles
Search /api/search/ Full-text search across all entities
Webhooks /api/webhooks/ Outgoing webhook configuration, for superusers only
Audit Log /api/audit-logs/ Immutable audit trail, and the action and record types its filters take
Dashboard Sync /api/remote-systems/ Health of the Dashboard Sync Senders and Sync now. With include_remote=true, /api/cases/ merges their cases in. See Dashboard Sync
Sync feed /api/sync/v1/cases/ The cases this installation sends to receiving installations. Accepts only the sync token
System /api/system-settings/ Tenant configuration and admin operations

See the built-in API reference at /api/docs/ for complete endpoint details, request/response schemas, and parameter documentation.

Filtering lists

The case list, the indicator registry and the audit log take a filter chain. Each filter row is one f query parameter in the form <operator>:<key>:<comparison>:<value>. These are the rows that Filter builds in the interface, and a filtered list shows them in its page address.

curl -H "Authorization: Bearer dfire_ak_abc123..." \
     "https://your-dfire-instance.com/api/cases/?f=and:severity:equals:high&f=not:project:equals:12"

DFIRe reads the rows from left to right, without precedence. The operator and keeps the records that matched so far and also match the row. The operator or adds the records that match the row, and not leaves them out. An or on the first row counts as and. The value is everything after the third colon, so it can hold a colon. Encode it for the URL, for example %20 for a space and %26 for &.

Kind of key Comparisons
Text contains, not-contains, equals, not-equals
Tags The same as text. A row matches when one of the tags matches. A not- comparison matches when no tag does, including on a record without tags.
Choice equals, not-equals
Date after, before

Text and tag comparisons ignore letter case. To match it, add .case to the comparison, as in equals.case. A choice key takes the value the API returns, such as high or amber_strict, or an ID. On the case list, project, lead, phase, category and verdict also take none, which selects the cases without one.

A date is a day (2026-09-30), a minute (2026-09-30T14:05) or an ISO 8601 time with an offset (2026-09-30T14:05:00+03:00). DFIRe reads a day or a minute in UTC. after starts at the next day or minute, and before ends where the day or minute starts. For example, f=and:created:after:2026-09-30 keeps the cases created from 1 October 00:00 UTC.

Endpoints Keys
GET /api/cases/, GET /api/cases/dashboard-stats/ Text: title, number, description. Tags: tags. Choice: severity, status (new, in_progress, pending, resolved), sla (at_risk, breached), mode, type (playbook ID), project, lead (user ID), phase, category (incident category ID), verdict (outcome verdict ID), and system (local or a Dashboard Sync Sender ID) for users who can see remote cases. Date: created, updated, closed.
GET /api/statistics/, GET /api/statistics/cases/ The keys of the case list, without system. Statistics count only the cases of this installation. The response repeats the rows it counted in filters.
GET /api/indicators/, GET /api/indicators/classification-counts/ Text: value, notes. Tags: tags. Choice: type (STIX type), confidence, tlp, published and revoked (yes, no). Date: first_seen, last_seen.
GET /api/audit-logs/ Text: user, record, ip. Choice: action, record_type. Date: time.

The indicator registry has no classification key. Use the classification parameter. A bulk indicator request that selects with filter_params takes the rows as a list in filter_params.f. An unknown key in filter_params returns status 400, and the error names the key. GET /api/audit-logs/action-types/ and GET /api/audit-logs/record-types/ list the values of action and record_type. With include_remote=true, the chain of the case list also applies to the cases received through Dashboard Sync.

A chain holds at most 20 rows, and a value at most 2,048 characters. A row that DFIRe cannot read returns status 400, and the error names the row by its number. The other query parameters of a list keep working, and the chain narrows their result.

List responses

Each entry of GET /api/cases/ carries the tags of the case, duplicate_count, the number of repeated cases that deduplication added to it, and updated_at, the time the case record last changed. Its lead_is_service_account is true when the lead investigator is a service account. origin is null for a case on this installation. With include_remote=true, the list also holds the cases received through Dashboard Sync, and their origin is the ID of the Dashboard Sync Sender. Remote cases need the permissions core.view_case and core.view_remotecase. With remote cases, ordering takes only created_at, -created_at and sla.

GET /api/indicators/?tree=true returns the registry as a hierarchy. Each matching indicator comes with the indicators above it. Such a parent has context set to true when it does not match the filters itself. Each row has its depth, 0 at the top level. limit and offset count top-level indicators, and each comes with its rows. The response adds top_level_count.

In the tree, ordering sorts the indicators at each level among themselves. It takes value, stix_type, classification, confidence, tlp, tag_count, case_count, enrichment, is_published, first_seen, last_seen, created_at and updated_at, with a leading - for descending order. Empty values come last in both directions. The default is -updated_at.

GET /api/audit-logs/ sorts by timestamp, user_name, action or target_model. It breaks ties on the entry ID, so paging through the log never skips or repeats an entry.

For a user with the permission auth.change_user, GET /api/users/ lists every account. For other users it lists only the active accounts, without service accounts. With include_service_accounts=true, their list also holds the active service accounts.

GET /api/cases/tags/ and GET /api/indicators/tags/ return the most used tags. See case tags and indicator tags.

What you may do on a record

The detail replies of a case and an evidence item carry allowed_operations, and so do the replies of the investigation report routes. It is a sorted list of operation names, such as case.update or item.delete. DFIRe computes the list with the decision each route uses: the route accepts an operation in the list and refuses one left out. List replies do not carry it.

A rule about one record still applies. For example, casechatmessage.edit covers your own messages, and a report section that has passed QA keeps its content until someone revokes the QA.

Refusals

A request that names a case you may not read answers 404, as a request for a missing case does. This holds for a case in the URL and for a case or item in the request body. A refused action on a case you may read answers 403. A refusal on a case or an upload session carries its text in detail. A role without the permission for the action gets 403 before DFIRe looks at the case. The permission is the one the action's operation names, the same in the web interface, the REST API and MCP. A write to a closed or archived case answers 403, and its detail names the case and asks you to reopen it. A method that a route does not serve answers 405 and asks no permission of the route. A route that reads the request body answers 400 to a JSON list, string, number or boolean, and reads null as no body. A refusal for a missing permission, a team role, a lead-only action or a case you may not read is recorded in the audit log. See Audit log → Refused requests.

Reads write nothing

GET /api/cases/{id}/investigation-report/ on a case whose report nobody has written returns the report it starts with. Its id, created_at and updated_at are null, on the report and on every section. The first write stores the report, for example a PATCH with {"sections": {}}.

A PATCH names each section by its ID, and DFIRe refuses a key that is not an ID with 400. A section for a template added later also has a null id until the next write. GET /api/preferences/ returns the defaults with updated_at set to null until the first PATCH.

Security Best Practices

  • Use service accounts for integrations. Avoid using personal API keys for automated systems. Service accounts make it clear which permissions are granted to which integration.
  • Set short expiration dates. Rotate keys regularly. Use the shortest lifetime that is practical for your integration.
  • Store keys in secrets managers. Never hardcode API keys in scripts, configuration files, or version control. Use your platform's secrets management (AWS Secrets Manager, HashiCorp Vault, environment variables).
  • Apply least privilege. Create dedicated groups with minimal permissions for each integration. A SIEM connector that only reads cases should not have write access.
  • Monitor usage. Review API key usage statistics and audit logs regularly. Disable keys that show unexpected activity or are no longer in use.
  • Disable before deleting. If you suspect that a key has leaked, disable it first. The key stops working immediately. Whoever held the key could act as its account, so also check that account for other keys you do not recognize. Then investigate before deciding whether to delete or regenerate.