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

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=..."
}
2

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
3

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)
4

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

​
API Key Scopes

Each API key is scoped to specific permissions:
ScopePermissions
investigations:readRead investigation sessions and results
investigations:writeStart investigations, send follow-ups
incidents:readList and view Sentinel incidents
search:readSearch investigations and entities
graph:readQuery 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.
1

Create an API Client

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

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"
}
3

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:
CookiehttpOnlySecureSameSitePurpose
access_tokenYesYesLaxAPI authorization JWT
refresh_tokenYesYesLaxToken renewal
token_expiryNoYesLaxClient-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:
RolePermissions
analystView and create investigations, search, view knowledge graph, manage own profile
adminAll 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.