Skip to main content
Service accounts are non-human identities that your applications, scripts, and integrations use to call the ContraForce v2 API. Each service account authenticates with a Client ID and Client Secret, and every credential carries its own set of granular API scopes that determine exactly what it can do across the organization.
Who is this for? Organization Admins and security engineers who need to connect external tools, SIEM pipelines, ticketing systems, or custom automations to ContraForce without using a human user account.

Prerequisites

  • Org Admin role to create a service account, change it, issue it a credential, or re-enable it. An API caller needs to be a service account whose own organizational role is Admin.
  • The org:service-accounts:manage API scope (or, in the portal, the Org Admin or User Admin role) to disable a service account, revoke a credential, or delete a service account
  • A clear understanding of the API scopes the integration needs — start with the minimum and expand as required
Service accounts can only call the v2 API (https://portal.contraforce.com/api/v2/...). Requests to the v1 API are rejected with 403 Forbidden.

How Authorization Works

Authorization for service accounts is driven by API scopes on each credential. Scopes define what a credential is allowed to call.
  • 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.
  • Granting access also needs the Admin role: scopes decide what a credential can call, but actions that grant access (changing organizational roles, creating service accounts, or issuing them credentials) also need the service account’s own organizational role to be Admin.

Where to Find Service Accounts

Navigate to Settings → Developers in the ContraForce Portal. Service accounts appear in the Integrations table alongside webhooks, marked with a key icon and the type Service Account.

Creating a Service Account

1

Open the Developers tab

In the Portal, go to Settings → Developers and click Add Integration → Service Account.
2

Enter basic details

Provide a Name (up to 200 characters) and an optional Description (up to 1000 characters). Use a name that identifies the calling system — for example, SIEM-ingest-prod or Ticketing-bridge.
3

Select API scopes for the initial credential

Pick the scopes the first credential should carry. Scopes follow the {resource}:{action} pattern and are grouped into Workspace Scopes (operate on workspace-owned resources such as incidents and Gamebooks) and Organization Scopes (operate on org-level resources such as users and webhooks).
Follow least-privilege. Grant only the scopes the integration actually calls. You can always issue a second credential with broader scopes later.
4

Optional — set credential expiration

Choose an expiration date if the credential should automatically stop working after a certain point. Leave blank for a credential that never expires.
5

Create and capture the secret

Click Create. ContraForce returns the Client ID and a Client Secret.
The Client Secret is shown once and cannot be retrieved again. Copy it immediately into your secret store (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, etc.). If you lose it, revoke the credential and issue a new one.

Authenticating to the v2 API

Service accounts use HTTP Basic authentication (RFC 7617). Encode ClientId:ClientSecret in Base64 and send it in the Authorization header.
On success, ContraForce records usage metadata on the credential (LastUsedAt) and writes an entry to the service account’s Request Logs.

Authentication failures

API Scopes Reference

Scopes are granted per credential. A service account can hold multiple credentials with different scope sets.

Workspace scopes

Authorize actions against workspace-owned resources. Cross-workspace endpoints use these scopes and automatically return only data from workspaces the service account is allowed to see.

Organization scopes

Authorize actions on org-level resources.
Write scopes imply their matching read scope. Granting incidents:write automatically authorizes incidents:read on the same endpoint set. gamebooks:execute does not imply gamebooks:read; grant both to submit runs and poll their results.

Endpoint Reference

Every v2 endpoint grouped by scope with full route paths

Object Models

Copy-pasteable JSON request and response examples

Running Gamebooks with a Service Account

A service account can start an incident-response Gamebook from your own tools, such as a SOAR platform or a ticketing workflow. The run goes through the same workspace Gamebook policies, integration permissions, and approval settings as a run started in the Portal, and the service account is recorded as the initiator in Gamebook history and the incident audit.

Set up the service account

1

Give the service account a workspace role

To run a Gamebook right away, the service account needs the Owner or Incident Responder role on the target workspace. With any other workspace role, it can only submit a run for approval ("isQueued": true). A role on a different workspace does not count.
2

Add the Gamebook scopes to the credential

When you create or edit the credential, select Gamebooks → Execute (gamebooks:execute). Also select Gamebooks → Read (gamebooks:read) to poll for results, and Incidents → Read (incidents:read) to look up the incident’s entities.
3

Review the workspace's Gamebook policies

Run policies treat a service-account run like one from a service provider managing the workspace, so policies that apply to anyone or to service providers also apply to it. Block the action stops the run, and Ask an approver first queues it for a person to approve in the Portal. Partner approval settings can also queue it.

Submit a run

  1. Pick the playbooks to run from the playbook catalog. Each entry lists the id and entityType to send and the kind of incident entity it acts on.
  2. Get the incident with GET /api/v2/workspaces/{workspaceId}/incidents/{source}/{incidentId} (incidents:read) and take the target’s id from investigationDetails.entities[]. See Finding the entityId.
  3. Submit the run with POST /api/v2/workspaces/{workspaceId}/gamebooks/run. See the Endpoint Reference for the request fields and validation rules.
  4. Store the returned data.id and poll GET /api/v2/workspaces/{workspaceId}/gamebooks/by-incident/{incidentId}?source={source}&withUserDetails=false until that Gamebook finishes.
The response tells you what happened to the run:

What a service account cannot do

  • Approve, retry, deny, or cancel a Gamebook. These stay in the Portal.
  • Run Block IP. Block IP is not available to service accounts yet, including runs submitted for approval.
  • Add an approval reason. Reasons are added as incident comments and are only available in the Portal.
Submitting a run is not idempotent: sending the same request twice can start two runs. After a timeout, check the incident’s Gamebook history before you resubmit, especially for containment actions.

Managing the Service Account

Open a service account’s detail page from Settings → Developers to manage it. The page has three tabs: General, Request Logs, and Audit.

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.
Deleting a service account breaks every integration using its credentials. Disable first and monitor Request Logs for any stragglers before deleting.

Credential management

Each credential shows its prefix (first 6 characters), status, expiration, scopes, last-used timestamp, and creation date.

Request Logs tab

Shows every API call made using any credential on the service account: timestamp, HTTP method, path, response status, latency, and source IP. Use this to audit integration behavior or troubleshoot 403 failures.

Audit tab

Shows lifecycle events — creation, updates, credential issuance, revocation, disable/enable, and deletion — attributed to the Portal user who performed each action.

Rotating a Credential (Zero Downtime)

Because a service account can hold multiple active credentials, you can rotate secrets without an outage.
1

Issue a new credential

On the service account’s General tab, click New Credential. Select the same scopes as the credential you’re rotating and copy the new Client Secret immediately.
2

Deploy the new secret

Update your integration’s secret store with the new Client Secret. Deploy the configuration change.
3

Verify traffic on the new credential

Check Request Logs and confirm that requests are coming in. The new credential’s Last used timestamp updates within seconds of the first authenticated call.
4

Revoke the old credential

Once all traffic has shifted, click Revoke on the old credential. Any residual caller using the old secret will receive 403 Forbidden.

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


Setting Up Webhooks

Send signed incident events to your ticketing system, SIEM, or chat tools from the same Developers tab.

User Roles & Permissions

See which organization roles can create, disable, and delete service accounts and API keys.

Error Reference

Look up v2 API error codes, such as INSUFFICIENT_SCOPE, with their HTTP status and what to do.
If you have questions about service accounts or need help planning an integration, contact us at support@contraforce.com.
Last modified on November 9, 2026