Authentication - SoCMate

SoCMate supports three authentication methods: OAuth2 Authorization Code flow for interactive users, API keys for simple machine integrations, and OAuth2 Client Credentials for service-to-service communication.

OAuth2 Authorization Code Flow

This is the primary authentication method for browser-based users. SoCMate uses Azure Entra ID (formerly Azure AD) as the identity provider.

Initiate login

Request an authorization URL from the API:

curl -X GET https://api.socmate.yourcompany.com/api/auth/login

Response:

{
  "auth_url": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id=...&response_type=code&redirect_uri=...&scope=openid+profile+email+User.Read&state=..."
}

User authenticates

Redirect the user to the auth_url. They authenticate with Azure Entra ID and complete MFA if required. Azure redirects back to your redirect_uri with an authorization code:

https://yourapp.com/auth/callback?code=0.AAAA...&state=random-state

Exchange code for tokens

Send the authorization code to the API:

curl -X POST https://api.socmate.yourcompany.com/api/auth/callback \
  -H "Content-Type: application/json" \
  -d '{
    "code": "0.AAAA...",
    "state": "random-state-string",
    "redirect_uri": "https://yourapp.com/auth/callback"
  }'

Response:

{
  "user": {
    "entra_id": "abc-def-123",
    "email": "analyst@example.com",
    "name": "Jane Analyst",
    "roles": ["analyst"]
  }
}

The response also sets three httpOnly cookies:

access_token — JWT for API authorization
refresh_token — token for renewal
token_expiry — expiration timestamp (readable by client-side JavaScript)

Make authenticated requests

Subsequent requests include the JWT automatically via cookies, or you can pass it as a Bearer token:

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

Token Refresh

Access tokens expire after a configurable period (default: 30 minutes). Use the refresh endpoint to obtain new tokens:

curl -X POST https://api.socmate.yourcompany.com/api/auth/refresh \
  -H "Cookie: refresh_token=..."

Response:

{
  "message": "Token refreshed"
}

The response sets updated cookies with new token values. The token_expiry cookie (not httpOnly) can be read by client-side JavaScript to proactively refresh before expiration.

The SoCMate UI automatically handles token refresh. If you are building a custom integration, check the token_expiry cookie and refresh the token before it expires.

API Key Authentication

API keys provide a simpler authentication method for automated integrations, scripts, and CI/CD pipelines. They do not require the OAuth2 flow.

Using an API Key

Pass the API key in the X-API-Key header:

curl -X GET https://api.socmate.yourcompany.com/api/v1/search?q=suspicious+login \
  -H "X-API-Key: YOUR_API_KEY_HERE"

import httpx

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

response = client.get("/api/v1/search", params={"q": "suspicious login"})
print(response.json())

const response = await fetch(
  "https://api.socmate.yourcompany.com/api/v1/search?q=suspicious+login",
  {
    headers: {
      "X-API-Key": "YOUR_API_KEY_HERE"
    }
  }
);
const data = await response.json();

API Key Scopes

Each API key is scoped to specific permissions:

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

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

Key Format

API keys follow the format sk_live_{key_id}{random_secret}. The key_id prefix is visible in the admin panel and in API responses; the full key is only shown once at creation time.

Store your API key securely. The full key is only displayed once when created or rotated. SoCMate stores only a salted hash of the key. If you lose the key, you must rotate it to generate a new one.

OAuth2 Client Credentials Flow

For service-to-service integrations (SOAR platforms, ticketing systems, custom automation), use the OAuth2 Client Credentials flow.

Create an API Client

An admin creates an API client in the SoCMate Admin panel. See API Clients for details.

Request an access token

curl -X POST https://auth.socmate.yourcompany.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=socmate-myapp-abc123" \
  -d "client_secret=your-client-secret"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 1800,
  "token_type": "Bearer"
}

Use the token

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

When using the browser-based OAuth2 flow, tokens are stored in cookies with the following security settings:

Cookie	httpOnly	Secure	SameSite	Purpose
`access_token`	Yes	Yes	Lax	API authorization JWT
`refresh_token`	Yes	Yes	Lax	Token renewal
`token_expiry`	No	Yes	Lax	Client-side expiry check

httpOnly prevents JavaScript from reading the token (XSS protection)
Secure ensures cookies are only sent over HTTPS
SameSite=Lax prevents CSRF for most cross-site requests
token_expiry is intentionally not httpOnly so the UI can check if a refresh is needed

User Info

Retrieve the authenticated user’s profile:

curl -X GET https://api.socmate.yourcompany.com/api/auth/userinfo \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response:

{
  "entra_id": "abc-def-123",
  "email": "analyst@example.com",
  "name": "Jane Analyst",
  "roles": ["analyst"],
  "profile": {
    "department": "Security Operations",
    "job_title": "SOC Analyst L2"
  }
}

Roles and Permissions

SoCMate uses role-based access control (RBAC) with two roles:

Role	Permissions
`analyst`	View and create investigations, search, view knowledge graph, manage own profile
`admin`	All analyst permissions plus user management, SIEM provider configuration, LLM model management, API key and client management

New users are assigned the analyst role on first login. Admins can promote users via the Admin panel.

Logout

Clear the authentication session:

curl -X POST https://api.socmate.yourcompany.com/api/auth/logout

This clears all authentication cookies and invalidates the session.

​OAuth2 Authorization Code Flow

​Token Refresh

​API Key Authentication

​Using an API Key

​API Key Scopes

​Key Format

​OAuth2 Client Credentials Flow

​Cookie Security

​User Info

​Roles and Permissions

​Logout

OAuth2 Authorization Code Flow

Token Refresh

API Key Authentication

Using an API Key

API Key Scopes

Key Format

OAuth2 Client Credentials Flow

Cookie Security

User Info

Roles and Permissions

Logout