API Clients - SoCMate

API clients enable OAuth2 Client Credentials authentication for service-to-service integrations. Unlike API keys (which use a static secret), API clients obtain short-lived JWT tokens, providing stronger security for production integrations.

When to Use API Clients vs API Keys

Feature	API Client (OAuth2)	API Key
Authentication	Client Credentials flow, short-lived JWT	Static key in header
Token Lifetime	30 minutes (configurable)	Months to years
Security	Higher — tokens expire automatically	Lower — must rotate manually
Setup Complexity	Moderate — requires token exchange	Simple — single header
Best For	Production SOAR integrations, microservices	Scripts, quick integrations, testing

Use API clients for production service-to-service integrations where security is a priority. Use API keys for simpler automation, one-off scripts, and development.

Creating an API Client

API client management requires the admin role.

From the UI

Navigate to Admin > API Clients and click Create Client. Provide a name, description, and select the scopes.

From the API

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

Response:

{
  "id": "6507f1f77bcf86cd799439011",
  "client_id": "socmate-xsoar-production-abc123",
  "client_secret": "generated-secret-value-shown-once",
  "name": "XSOAR Production",
  "scopes": ["investigations:read", "investigations:write", "incidents:read"],
  "token_endpoint": "https://auth.socmate.yourcompany.com/oauth/token"
}

The client_secret is shown only once in this response. Copy it immediately and store it securely. SoCMate cannot recover the secret — you would need to regenerate it.

Using an API Client

API clients authenticate using the OAuth2 Client Credentials flow:

Request an access token

Exchange the client credentials for a JWT access token:

curl -X POST https://auth.socmate.yourcompany.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=socmate-xsoar-production-abc123" \
  -d "client_secret=generated-secret-value"

import httpx

TOKEN_URL = "https://auth.socmate.yourcompany.com/oauth/token"

response = httpx.post(TOKEN_URL, data={
    "grant_type": "client_credentials",
    "client_id": "socmate-xsoar-production-abc123",
    "client_secret": "generated-secret-value",
})

token = response.json()["access_token"]

const tokenResponse = await fetch(
  "https://auth.socmate.yourcompany.com/oauth/token",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: "socmate-xsoar-production-abc123",
      client_secret: "generated-secret-value",
    }),
  }
);

const { access_token } = await tokenResponse.json();

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 1800,
  "token_type": "Bearer",
  "scope": "investigations:read investigations:write incidents:read"
}

Use the token

Pass the access token as a Bearer token in the Authorization header:

curl -X GET https://api.socmate.yourcompany.com/api/v1/search?q=phishing \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Refresh before expiration

Tokens expire after 30 minutes (configurable). Your integration should request a new token before the current one expires. There is no refresh token in the Client Credentials flow — simply request a new access token.

import time

token_data = None
token_expiry = 0

def get_token():
    global token_data, token_expiry
    if time.time() < token_expiry - 60:  # Refresh 60s before expiry
        return token_data["access_token"]

    response = httpx.post(TOKEN_URL, data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    })
    token_data = response.json()
    token_expiry = time.time() + token_data["expires_in"]
    return token_data["access_token"]

Scopes

API clients use the same scope system as API keys:

Scope	Permissions
`investigations:read`	Read investigation sessions and results
`investigations:write`	Start investigations, send follow-ups
`incidents:read`	List and view Sentinel incidents
`search:read`	Search investigations and entities
`graph:read`	Query the knowledge graph

Scopes are validated at creation time. Invalid scopes are rejected with a 400 error.

Listing API Clients

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

Response:

{
  "clients": [
    {
      "id": "6507f1f77bcf86cd799439011",
      "client_id": "socmate-xsoar-production-abc123",
      "name": "XSOAR Production",
      "description": "Palo Alto XSOAR integration for automated investigation",
      "status": "active",
      "scopes": ["investigations:read", "investigations:write", "incidents:read"],
      "created_by": "admin-user-id",
      "created_at": "2026-03-27T00:00:00Z",
      "last_used_at": "2026-03-27T10:30:00Z"
    }
  ],
  "total": 1
}

The client secret is never returned in list or detail responses.

Regenerating a Secret

If a client secret is compromised or lost, regenerate it:

curl -X POST https://api.socmate.yourcompany.com/api/admin/api-clients/socmate-xsoar-production-abc123/regenerate-secret \
  -H "Authorization: Bearer <admin_token>"

Response:

{
  "client_id": "socmate-xsoar-production-abc123",
  "client_secret": "new-secret-value-shown-once"
}

Regenerating the secret immediately invalidates the old secret. Any integrations using the old secret will fail authentication. Unlike API key rotation, there is no grace period. Coordinate the update with your integration team.

Disabling a Client

Disable a client to revoke all access:

curl -X DELETE https://api.socmate.yourcompany.com/api/admin/api-clients/socmate-xsoar-production-abc123 \
  -H "Authorization: Bearer <admin_token>"

Response:

{
  "success": true
}

Disabled clients:

Cannot obtain new tokens
Existing tokens remain valid until they expire (up to 30 minutes)
Cannot be re-enabled — create a new client instead

Client Status

Status	Description
`active`	Client can obtain tokens and authenticate
`disabled`	Client has been disabled; cannot obtain new tokens

Best Practices

Use descriptive names — Name clients after the integration they serve
Minimize scopes — Only grant the scopes needed for the specific integration
Cache tokens — Reuse tokens until near expiration instead of requesting a new one per API call
Store secrets securely — Use Azure Key Vault or a similar secrets manager
Monitor last_used_at — Identify and disable unused clients
Separate clients per environment — Use different clients for dev, staging, and production

​When to Use API Clients vs API Keys

​Creating an API Client

​From the UI

​From the API

​Using an API Client

​Scopes

​Listing API Clients

​Regenerating a Secret

​Disabling a Client

​Client Status

​Best Practices

When to Use API Clients vs API Keys

Creating an API Client

From the UI

From the API

Using an API Client

Scopes

Listing API Clients

Regenerating a Secret

Disabling a Client

Client Status

Best Practices