Service Accounts

​

Prerequisites

• Organization Admin role, or the org:service-accounts:manage API scope on an existing credential
• A clear understanding of the API scopes the integration needs — start with the minimum and expand as required

​

How Authorization Works

• Scopes decide what — each scope (for example, incidents:read) authorizes a specific class of API action.
• Cross-workspace by default — v2 endpoints that span workspaces (such as POST /api/v2/incidents/across-workspaces) run as scope-authorized calls and return data from every workspace the service account can see in one request. There is no need to target a single workspace per call.
• Multiple credentials per account — a single service account can carry several credentials, each with a different scope set and expiration. This enables zero-downtime rotation and lets one integration hold read-only scopes while another carries write scopes.

​

Where to Find Service Accounts

​

Creating a Service Account

​

Authenticating to the v2 API

curl https://portal.contraforce.com/api/v2/incidents/across-workspaces \
  -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"isFirstCall": true}'

​

Authentication failures

​

API Scopes Reference

​

Workspace scopes

​

Organization scopes

​

Managing the Service Account

​

General tab

• Disable — Blocks all credentials on the service account from authenticating. Use this for a temporary freeze (for example, during an incident).
• Enable — Re-activates a disabled service account.
• Delete — Permanently removes the service account and all its credentials. Cannot be undone.
• Edit — Update name and description.

​

Credential management

​

Request Logs tab

​

Audit tab

​

Rotating a Credential (Zero Downtime)

​

How Service Accounts Work

• Identity — Each service account is an organization member with IsServiceAccount = true. It is not visible in Settings → User Management and cannot sign in to the Portal.
• Client ID — The stable GUID of the service account. Safe to share.
• Client Secret — 32 cryptographically random bytes, Base64-encoded. Stored as a SHA-256 hash (for authentication lookups) and as AES-256-GCM ciphertext wrapped by an RSA key in Azure Key Vault (envelope encryption). The plaintext is shown only at creation.
• Authorization — Every v2 endpoint declares a required scope. On each request, the authentication middleware resolves the credential, confirms it is active and unexpired, and projects its scopes onto the request principal. The endpoint’s scope filter then allows or denies. Endpoints that span workspaces filter returned data to the set of workspaces the service account is entitled to see.
• Isolation — Service accounts are deliberately restricted to the v2 API. The v2 design uses resource-based routing with per-request scope authorization, removing an authorization bypass that existed in v1.

​

Best Practices

• One service account per integration. Don’t share credentials across systems — it fragments audit trails and breaks rotation.
• Split read and write. Issue separate credentials for read-only monitoring and write automations on the same service account, so a leak of the monitoring secret can’t mutate state.
• Minimum scopes. Grant read-only scopes first. Add write scopes only when an integration actually needs to mutate state.
• Expiration everywhere. Set a credential expiration for anything non-critical and renew on a schedule.
• Name for humans. Future-you will grep the audit log. Jira-incident-sync-prod beats sa-3.
• Monitor the Request Logs. A sudden drop in traffic usually means a rotation went wrong. A sudden spike may mean a runaway script.

​

Troubleshooting