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();

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/sessions/`, `GET /api/v1/investigations/`
`investigations:write`	`POST /api/v1/investigations/start`, `POST /api/v1/sessions/*/message`
`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

​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

Scopes

Key Rotation

Listing API Keys

Disabling an API Key

Key Status

Best Practices