API Keys - SoCMate

API keys provide a simple, long-lived authentication method for scripts, automation, CI/CD pipelines, and third-party integrations that need to access SoCMate programmatically.

Creating an API Key

API key management requires the admin role. Only administrators can create, rotate, and disable API keys.

From the UI

Navigate to Admin > API Keys and click Create API Key. Provide a name, description, and select the scopes the key should have access to.

From the API

curl -X POST https://api.socmate.yourcompany.com/api/admin/api-keys \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SOAR Integration",
    "description": "API key for Palo Alto XSOAR integration",
    "scopes": ["investigations:read", "investigations:write", "incidents:read"],
    "expires_in_days": 365
  }'

Response:

{
  "id": "6507f1f77bcf86cd799439011",
  "key_id": "k_abc123",
  "api_key": "sk_live_k_abc123_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a",
  "name": "SOAR Integration",
  "scopes": ["investigations:read", "investigations:write", "incidents:read"],
  "expires_at": "2027-03-27T00:00:00Z",
  "header_name": "X-API-Key"
}

The full API key is only shown once in this response. Copy it immediately and store it securely (e.g., in a secrets manager). SoCMate stores only a salted hash of the key and cannot recover it.

Using an API Key

Pass the API key in the X-API-Key header with every request:

curl -X GET https://api.socmate.yourcompany.com/api/v1/search?q=ransomware \
  -H "X-API-Key: sk_live_k_abc123_7f8a9b0c..."

import httpx

client = httpx.Client(
    base_url="https://api.socmate.yourcompany.com",
    headers={"X-API-Key": "sk_live_k_abc123_7f8a9b0c..."}
)

# Search investigations
results = client.get("/api/v1/search", params={"q": "ransomware"}).json()

# Start an investigation
session = client.post("/api/v1/investigations/start", json={
    "query": "Check for ransomware indicators in the last 24 hours",
    "persona": "soc_analyst",
    "provider": "sentinel",
}).json()

const API_KEY = "sk_live_k_abc123_7f8a9b0c...";
const BASE_URL = "https://api.socmate.yourcompany.com";

const response = await fetch(`${BASE_URL}/api/v1/search?q=ransomware`, {
  headers: { "X-API-Key": API_KEY }
});
const data = await response.json();

Synchronous investigation timeout

Omit background (or set it to false) to receive the investigation result in one response. The production ingress and frontend proxy allow up to 30 minutes of upstream inactivity. Configure your HTTP client to wait at least that long; for example, use curl --max-time 1860 to allow a small transport margin. These are proxy inactivity limits, not an investigation execution deadline. The frontend setting applies to its rewritten proxy requests, and the production ingress annotations apply to the routes on that ingress. Any additional proxy in a custom installation must also allow the required wait time.

Background investigations and polling

For long investigations, use background: true to avoid holding the request open through proxy timeouts. Set SOCMATE_API_KEY to a key with both investigations:write and investigations:read scopes:

curl 'https://agent.socmate.yourcompany.com/api/v1/public/investigate' \
  -H "X-API-Key: ${SOCMATE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"query":"Investigate failed sign-ins in the last hour","background":true}'

The response contains session_id, run_id, and a browser session_url. Poll with the returned session ID using the same API key:

curl 'https://agent.socmate.yourcompany.com/api/v1/public/sessions/<session_id>' \
  -H "X-API-Key: ${SOCMATE_API_KEY}"

Check session.status every few seconds. Continue while it is initialized or active; stop when it becomes completed, failed, or canceled. The response also includes persisted messages, events, and tool_calls. A successful GET returns HTTP 200 even when the investigation status is failed. This reuses the session-history response: the POST options such as include_tool_calls and include_raw_results do not filter polling results. History may be partial while the investigation is running. Polling reads persisted state; it does not restart an investigation interrupted by a service restart. The public route requires investigations:read and ownership by the creating key ID. Rotating that key preserves ownership; creating a different key does not. Internal /api/v1/sessions/* routes continue to reject API keys. Missing or invalid authentication returns 401, insufficient scope or ownership returns 403, and an unknown session returns 404. For installations accessed through the frontend proxy, use https://<frontend-host>/proxy/agent/api/v1/public/... for both requests.

Scopes

Each API key is restricted to a set of scopes that control which endpoints it can access:

Scope	Endpoints Accessible
`investigations:read`	`GET /api/v1/public/sessions/{session_id}`
`investigations:write`	`POST /api/v1/public/investigate`
`incidents:read`	`GET /api/v1/incidents`, `GET /api/v1/incidents/*`
`search:read`	`GET /api/v1/search`, `GET /api/v1/search/*`
`graph:read`	`GET /api/v1/graph/*`

A request to an endpoint outside the key’s scopes returns 403 Forbidden:

{
  "detail": "API key does not have the required scope: investigations:write"
}

Key Rotation

Rotate an API key to generate a new secret without changing the key ID. This allows you to update integrations gradually with an optional grace period for the old key.

curl -X POST https://api.socmate.yourcompany.com/api/admin/api-keys/k_abc123/rotate \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "grace_period_days": 7,
    "expires_in_days": 365
  }'

Response:

{
  "key_id": "k_abc123",
  "api_key": "sk_live_k_abc123_newkeyvalue...",
  "expires_at": "2027-03-27T00:00:00Z",
  "previous_key_expires_at": "2026-04-03T00:00:00Z"
}

Parameter	Default	Description
`grace_period_days`	`7`	Days the old key continues to work (0 = immediate invalidation)
`expires_in_days`	—	New expiration (defaults to the existing expiration if not set)

During the grace period, both the old and new API keys are accepted. This gives you time to update all integrations before the old key expires.

Listing API Keys

List all API keys with optional search:

curl -X GET "https://api.socmate.yourcompany.com/api/admin/api-keys?search=SOAR" \
  -H "Authorization: Bearer <admin_token>"

Response:

{
  "api_keys": [
    {
      "id": "6507f1f77bcf86cd799439011",
      "key_id": "k_abc123",
      "key_prefix": "sk_live_k_abc123",
      "name": "SOAR Integration",
      "description": "API key for Palo Alto XSOAR integration",
      "status": "active",
      "scopes": ["investigations:read", "investigations:write", "incidents:read"],
      "created_by": "admin@example.com",
      "created_at": "2026-03-27T00:00:00Z",
      "updated_at": "2026-03-27T00:00:00Z",
      "expires_at": "2027-03-27T00:00:00Z",
      "last_used_at": "2026-03-27T10:30:00Z",
      "last_rotated_at": null,
      "previous_key_expires_at": null
    }
  ],
  "total": 1
}

The list never exposes the full API key value — only the key_prefix is shown.

Disabling an API Key

Disable a key to immediately revoke access:

curl -X DELETE https://api.socmate.yourcompany.com/api/admin/api-keys/k_abc123 \
  -H "Authorization: Bearer <admin_token>"

Disabling a key also invalidates any grace-period previous key value. The key cannot be rotated after disabling.

Key Status

Status	Description
`active`	Key is valid and can be used for authentication
`expired`	Key has passed its expiration date
`disabled`	Key has been manually disabled by an admin

Best Practices

Use scoped keys — Only grant the minimum scopes needed for each integration
Set expiration dates — Do not create keys that never expire; use the expires_in_days parameter
Rotate regularly — Use the rotation endpoint with a grace period to update keys without downtime
Monitor usage — Check last_used_at in the admin panel to identify unused keys for cleanup
Use descriptive names — Name keys after the integration they serve (e.g., “SOAR Integration”, “CI Pipeline”)
Store securely — Use a secrets manager (Azure Key Vault, HashiCorp Vault) rather than embedding keys in code

​Creating an API Key

​From the UI

​From the API

​Using an API Key

​Synchronous investigation timeout

​Background investigations and polling

​Scopes

​Key Rotation

​Listing API Keys

​Disabling an API Key

​Key Status

​Best Practices

Creating an API Key

From the UI

From the API

Using an API Key

Synchronous investigation timeout

Background investigations and polling

Scopes

Key Rotation

Listing API Keys

Disabling an API Key

Key Status

Best Practices