API access

Overview

Every action available in the DFIRe web interface is also available through the REST API, apart from managing your own multi-factor authentication, which needs 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 multi-factor settings.

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.

Key Properties

Managing API Keys

In the same API Keys view you can:

• Enable / Disable. Temporarily suspend a key without deleting it
• Regenerate. Create a new key value (the old value stops working immediately)
• 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:

Admin Key Management

Superusers can manage any account's API keys from Settings → User Accounts, by editing the user. This includes creating, listing, editing, disabling, regenerating, and deleting keys.

The Edit userapikey permission adds key administration to a role without letting it hand out access. It works alongside the user permissions that open Settings → User Accounts in the first place, so a role needs both to manage anyone else's keys. A key authenticates as the account it belongs to and carries that account's permissions, so issuing one is equivalent to lending out the account. What the permission allows therefore depends on the account:

• Service accounts: everything, including creating and regenerating keys. This is the account type meant to be driven by a key.
• Ordinary accounts: listing, editing, disabling, and deleting the keys that already exist. New keys cannot be issued and existing ones cannot be regenerated. People create their own keys from their profile.
• System Root accounts: nothing. Only another superuser can manage a superuser's 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, and hides the account from non-admin user listings.

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

   Still in Settings → User Accounts, edit the service account and create the key from its API Keys section.

The setting is one-way because it decides who may issue keys for the account, and a key authenticates as the account it belongs to. 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.

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/

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/

Authentication Behavior

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.

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

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

Key Endpoint Groups

The API is organized into the following groups:

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

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 a key may be compromised, disable it first to immediately block access, then investigate before deciding whether to delete or regenerate.