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"]
}'
{
"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"
{
"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 |
400 error.
Listing API Clients
curl -X GET "https://api.socmate.yourcompany.com/api/admin/api-clients?search=XSOAR" \
-H "Authorization: Bearer <admin_token>"
{
"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
}
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>"
{
"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>"
- 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
