API Access

Overview

Every action available in the DFIRe web interface is also available through the REST API. 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.

Creating an API Key

1. Navigate to Settings > 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

From the API Keys settings page 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

Users with the change_tenant permission (superusers and tenant administrators) can manage any user's API keys from the user detail view. This includes listing, disabling, and deleting keys belonging to other users.

Service Accounts

Service accounts are dedicated user accounts designed for automated systems. They authenticate exclusively via API key — password login and SSO are blocked.

Creating a Service Account

1. Create a new user account

   Go to Settings > User Management and create a regular user account (e.g., 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 groups

   Add the service account to the groups that grant the permissions it needs. Follow the principle of least privilege.

4. Create an API key

   As an administrator, create an API key for the service account from Settings > API Keys using the user selector.

Custom Permissions via Groups

API keys inherit all permissions from the user account they belong to, including group memberships. To grant a service account (or any API key holder) a custom set of permissions, create a dedicated user group and assign only the rights that integration needs. Group creation is available exclusively through the Django admin panel at /admin/auth/group/. Once a group exists, its permissions can be managed from either the Django admin or from DFIRe Settings > User Management by editing the group. Assign the service account to this group to activate the permissions. This approach lets you enforce least privilege — for example, a SIEM connector group might only have view permissions on cases and indicators, while a SOAR playbook group could additionally have add and change permissions on cases.

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

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.