Partner API - ContraForce

The ContraForce Partner API enables programmatic access to your security data. Build custom integrations, sync incidents with your ITSM, or create automated workflows with your existing tools.

Full API documentation, including detailed request/response schemas, is available on GitHub: ContraForce API Documentation

Why Use the Partner API?

ITSM Integration

Sync incidents with ServiceNow, Jira, Autotask, and more

Custom Dashboards

Build internal reporting within your custom dashboard

SOAR Automation

Trigger workflows in your existing SOAR platform

Common Use Cases

Use Case	Description
Ticket Creation	Automatically create tickets in your PSA when incidents are detected
Bi-directional Sync	Keep incident status synchronized between ContraForce and your ITSM
Executive Reporting	Pull incident data into custom reports and dashboards
Alert Routing	Send incident notifications to custom channels (Slack, Teams, PagerDuty)
Data Warehouse	Export incident data to your data lake for long-term analysis

Getting Started

Prerequisites

Before using the API, you’ll need:

ContraForce Account

An active ContraForce account with API access enabled

API Credentials

Client ID and Client Secret from your ContraForce administrator

Workspace Access

Appropriate permissions to the workspaces you want to query

Obtaining API Credentials

Contact Your Administrator

Request API credentials from your ContraForce account administrator

Receive Credentials

You’ll receive a Client ID and Client Secret

Store Securely

Store credentials securely—never commit them to source control

Treat your API credentials like passwords. Never expose them in client-side code, public repositories, or logs.

Authentication

The ContraForce API uses OAuth 2.0 client credentials flow for authentication.

Getting an Access Token

curl -X POST https://api.contraforce.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Token

Include the access token in the Authorization header for all API requests:

curl -X GET https://api.contraforce.com/v1/incidents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Access tokens expire after 1 hour. Implement token refresh logic in your integration to handle expiration gracefully.

API Endpoints

The Partner API provides access to incidents and their associated data.

Base URL

https://api.contraforce.com/v1

Available Endpoints

Endpoint	Method	Description
`/incidents`	GET	List all incidents
`/incidents/{id}`	GET	Get incident details
`/incidents/{id}/entities`	GET	List entities for an incident
`/incidents/{id}/evidence`	GET	List evidence for an incident

API Components

Incident Object
List Incidents
Get Incident Details
List Entities
List Evidence

The core data structure representing a security incident.Key Fields:

Field	Type	Description
`id`	string	Unique incident identifier
`title`	string	Incident title/name
`severity`	string	High, Medium, Low, Informational
`status`	string	New, Active, Closed
`workspaceId`	string	Associated workspace
`createdAt`	datetime	When incident was created
`updatedAt`	datetime	Last modification time

Full Schema →

Retrieve a list of incidents with optional filtering.Endpoint: GET /incidentsQuery Parameters:

Parameter	Type	Description
`workspaceId`	string	Filter by workspace
`status`	string	Filter by status
`severity`	string	Filter by severity
`limit`	integer	Max results (default: 100)
`offset`	integer	Pagination offset

Full Documentation →

Retrieve complete details for a specific incident.Endpoint: GET /incidents/{id}Response includes:

Full incident metadata
Classification information
Assignment details
Timeline data

Full Documentation →

Get all entities (users, devices, IPs) associated with an incident.Endpoint: GET /incidents/{id}/entitiesEntity Types:

Users/Accounts
Devices/Endpoints
IP Addresses
Files/Hashes
URLs/Domains

Full Documentation →

Retrieve raw evidence and logs associated with an incident.Endpoint: GET /incidents/{id}/evidenceEvidence includes:

Raw log entries
Alert details
Forensic artifacts

Full Documentation →

Example Requests

List High Severity Incidents

curl -X GET "https://api.contraforce.com/v1/incidents?severity=High&status=Active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Incident Details

curl -X GET "https://api.contraforce.com/v1/incidents/INC-12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

List Incident Entities

curl -X GET "https://api.contraforce.com/v1/incidents/INC-12345/entities" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response: List Incidents

{
  "data": [
    {
      "id": "INC-12345",
      "title": "Suspicious login activity detected",
      "severity": "High",
      "status": "Active",
      "workspaceId": "ws-abc123",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T14:22:00Z"
    },
    {
      "id": "INC-12346",
      "title": "Malware detected on endpoint",
      "severity": "High",
      "status": "Active",
      "workspaceId": "ws-abc123",
      "createdAt": "2024-01-15T11:45:00Z",
      "updatedAt": "2024-01-15T11:45:00Z"
    }
  ],
  "pagination": {
    "total": 47,
    "limit": 100,
    "offset": 0
  }
}

Rate Limits

The API implements rate limiting to ensure fair usage and platform stability.

Limit Type	Value
Requests per minute	60
Requests per hour	1,000
Max results per request	100

Rate Limit Headers

Each response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705320000

If you exceed rate limits, you’ll receive a 429 Too Many Requests response. Implement exponential backoff in your integration.

Error Handling

The API uses standard HTTP status codes and returns detailed error messages.

HTTP Status Codes

Code	Meaning	Action
`200`	Success	Request completed successfully
`400`	Bad Request	Check request parameters
`401`	Unauthorized	Verify credentials/token
`403`	Forbidden	Check workspace permissions
`404`	Not Found	Verify resource ID exists
`429`	Rate Limited	Implement backoff and retry
`500`	Server Error	Retry after delay; contact support if persistent

Error Response Format

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'severity' parameter must be one of: High, Medium, Low, Informational",
    "details": {
      "parameter": "severity",
      "provided": "Critical",
      "allowed": ["High", "Medium", "Low", "Informational"]
    }
  }
}

Best Practices

Implement pagination

Always use pagination for list endpoints. Don’t assume you’ll receive all results in one request. Use limit and offset parameters to iterate through large result sets.

Handle rate limits gracefully

Monitor X-RateLimit-Remaining headers and implement exponential backoff when approaching limits. Don’t retry immediately on 429 responses.

Cache when appropriate

Cache incident details that don’t change frequently. Use updatedAt timestamps to invalidate cache entries when data changes.

Use webhooks for real-time updates

Instead of polling the API frequently, consider using webhooks (if available) or longer polling intervals with status filters.

Secure your credentials

Store API credentials in environment variables or a secrets manager. Never hardcode credentials or commit them to source control.

Log API interactions

Maintain logs of API requests and responses for debugging. Mask sensitive data like tokens in logs.

SDK & Libraries

While the API can be called directly with HTTP requests, you may find these helpful:

Language	Option
Python	Use `requests` library with OAuth2 session
JavaScript	Use `axios` or `fetch` with token management
PowerShell	Use `Invoke-RestMethod` cmdlet
C#	Use `HttpClient` with `System.Net.Http`

Check the GitHub repository for example code and community-contributed libraries.

Troubleshooting

Common Issues

Issue	Possible Cause	Solution
`401 Unauthorized`	Expired or invalid token	Refresh your access token
`403 Forbidden`	Missing workspace access	Verify API credentials have access to the workspace
`Empty results`	Filter too restrictive	Broaden filter criteria or check workspace ID
`Timeout errors`	Large result set	Use pagination with smaller `limit` values

API Documentation

GitHub: ContraForce API

Complete API documentation including schemas, examples, and changelog

Quick Links

ServiceNow Integration

Built-in ServiceNow ticketing integration

Jira Integration

Connect Jira Service Desk

API Enterprise Application

API permissions and authentication setup

Capabilities Matrix

Full integration capabilities

Questions about the Partner API? Contact us at [email protected].

​Why Use the Partner API?

ITSM Integration

Custom Dashboards

SOAR Automation

​Common Use Cases

​Getting Started

​Prerequisites

​Obtaining API Credentials

​Authentication

​Getting an Access Token

​Response

​Using the Token

​API Endpoints

​Base URL

​Available Endpoints

​API Components

​Example Requests

​List High Severity Incidents

​Get Incident Details

​List Incident Entities

​Example Response: List Incidents

​Rate Limits

​Rate Limit Headers

​Error Handling

​HTTP Status Codes

​Error Response Format

​Best Practices

​SDK & Libraries

​Troubleshooting

​Common Issues

​API Documentation

GitHub: ContraForce API

​Quick Links

​Related Guides

ServiceNow Integration

Jira Integration

API Enterprise Application

Capabilities Matrix

Why Use the Partner API?

Common Use Cases

Getting Started

Prerequisites

Obtaining API Credentials

Authentication

Getting an Access Token

Response

Using the Token

API Endpoints

Base URL

Available Endpoints

API Components

Example Requests

List High Severity Incidents

Get Incident Details

List Incident Entities

Example Response: List Incidents

Rate Limits

Rate Limit Headers

Error Handling

HTTP Status Codes

Error Response Format

Best Practices

SDK & Libraries

Troubleshooting

Common Issues

API Documentation

Quick Links

Related Guides