Coalition Control API - Basics and QuickStart

Overview

The Coalition Control API is a RESTful API, which means it uses standard HTTP requests (like GET, POST, PUT, DELETE) to perform actions. You can use cURL or the api client of your choice such as Postman. 

The API documentation can be found here: https://api.control.coalitioninc.com/docs/api 

The documentation is organized into key sections based on functionality: auth (authentication), user (user data), asm (Attack Surface Monitoring), and er (Executive Risks). 

The Base URL for requests is : https://api.control.coalitioninc.com

The Authentication Flow: Your First Step

Before you can access any data, you must authenticate and obtain the Bearer Token. This is a two-step process:

1. Request an Access Token: Send a POST request to the /auth/login endpoint with your user credentials (username and password) in the request body (If you are using MFA for your Coalition Control user you will need to disable MFA for that user).
2. Use the Token: The API will respond with an access token. This token is your key to all other API endpoints. For every subsequent request, you must include this token in the Authorization header, formatted as Bearer YOUR_ACCESS_TOKEN. Without it, you will get a 401 Unauthorized error.

Example Request (using cURL)

curl --request POST \
  --url https://api.control.coalitioninc.com/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
  "username": "your_email@example.com",
  "password": "your_password"
}'

Example request using the Authorization Token (using cURL)

curl --location 'https://api.control.coalitioninc.com/ENDPOINT' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data ''

3. Exploring Key Endpoints

Once authenticated, you can explore the data. A good place to start is the asm (Attack Surface Monitoring) section, as it has the most information useful for security practitioners. 

• Getting the Entity ID: The entity_ID is necessary for many requests in Coalition Control. Use a GET request to /asm/me/
• Getting Assets: There are three endpoints that are useful to get the detected assets that are in Coalition Control. You will need the Entity_ID included on the request.
  • Assets impacted by a risk finding: Use GET /asm/entity/{entity_id}/assets/impacted
  • Assets by domain/subdomain: Use GET /asm/entity/{entity_id}/ip_addresses
  • Assets by IP Address: Use GET /asm/entity/{entity_id}/ip_addresses
• Getting Security Findings: To get security findings use /asm/entity/{entity_id}/findings
• Getting Data Leaks: To get data leaks use /asm/entity/{entity_id}/dataleaks 

*Remember to always include your access token in the Authorization header for these calls.

Example Flow for Retrieving Security Findings

This is an example to demonstrate a successful API call with the authorization step.

1. Get Access Token Example Request (using curl)

curl --request POST \
  --url https://api.control.coalitioninc.com/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
  "username": "your_email@example.com",
  "password": "your_password"
}'

1. GET Entitiy_ID

curl --location 'https://api.control.coalitioninc.com/asm/me' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data ''

2. GET Security Findings

curl --location 'https://api.control.coalitioninc.com/asm/entity/{ENTITY_ID}/findings' \
--header 'Your_Access_Token'