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..."

​
Scopes

Each API key is restricted to a set of scopes that control which endpoints it can access:
ScopeEndpoints Accessible
investigations:readGET /api/v1/sessions/*, GET /api/v1/investigations/*
investigations:writePOST /api/v1/investigations/start, POST /api/v1/sessions/*/message
incidents:readGET /api/v1/incidents, GET /api/v1/incidents/*
search:readGET /api/v1/search, GET /api/v1/search/*
graph:readGET /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"
}
ParameterDefaultDescription
grace_period_days7Days 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

StatusDescription
activeKey is valid and can be used for authentication
expiredKey has passed its expiration date
disabledKey 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