Prerequisites: Authentication

Before making any API calls, you'll need to authenticate your requests.

1. Generate an API Key: Log in to your Bright Security account and navigate to the API key management section within your user or organization settings.
2. Create a New Key: Use one of the following in the Authorization header:.
3. Use the Key: Include this API key in the Authorization header of every API request you make.
   1. API Key: Authorization: Api-Key [YOUR_BRIGHT_API_KEY]
4. Partner Identification Header (Required) For analytics and support purposes, we require you to add the following header to every API call. This allows us to identify which partner integration is making the request.
   • Header: X-Bright-Integration
   • Value: [Your Company Name]

📘

Use least‑privilege keys. For the endpoints below you’ll typically need projects:read, issues:read, and optionally groups:read.

Workflow: Retrieving Project & Vulnerability Data

Here’s the step-by-step process for getting all the necessary information, from a high-level project list down to the details of a single vulnerability.

Step 1: Get All Available Projects

This call returns a paginated array of all available project objects. You'll parse this response to extract the unique ID (projectId) for each project.

• Endpoint: GET /api/v2/projects
• Required Scopes: projects:read OR projects:admin
• Request Example: GET /api/v2/projects?limit=100&offset=0

Step 2: Get Vulnerabilities for a Specific Project

Use a projectId to retrieve all the issues (vulnerabilities) identified within that project. This endpoint returns a paginated list of all vulnerabilities.

• Endpoint: GET /api/v2/projects/{projectId}/issues
• Required Scopes: projects:read OR projects:admin
• Request Example: GET /api/v2/projects/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8/issues?limit=100

Step 3: Get Detailed Information for a Single Vulnerability

Use the projectIssueId obtained in Step 2 to get rich context about a single vulnerability. Note that this endpoint uses API v1.

• Endpoint: GET /api/v1/project-issues/{projectIssueId}
• Required Scopes: projects:read OR projects:admin
• Request Example: GET /api/v1/project-issues/98765

Step 4 (Optional): Get Host Summaries

For performance reasons, host data is served separately from the main project details. Use these summary endpoints to get a list of hosts associated with a project's entry points or its identified issues.

• For Project Entry Points:
  • Endpoint: GET /api/v2/projects/{projectId}/entry-points/summary
  • Required Scopes: entry-points OR entry-points:read
  • Endpoint: Returns a summary of hosts related to all scanned entry points in the project.
• For Project Issues:
  • Endpoint: GET /api/v2/projects/{projectId}/issues/summary
  • Required Scopes: projects:read OR projects:admin
  • Endpoint: Returns a summary of hosts where vulnerabilities have been found. This list may be smaller than the entry points summary.

Handling Pagination

Our API uses two different pagination methods depending on the nature of the data. It's crucial to use the correct method for each endpoint.

Offset-based Pagination (for static data)

This method is simpler and is used for data that doesn't change often.

• Used for: GET /api/v2/projects
• Parameters:
  • limit: The maximum number of items per response.
  • offset: The number of items to skip from the beginning of the list.
• How it works: To get the next page of results, increment the offset by the limit value from your previous request. The process is complete when the API returns an empty list.
  • Page 1: ?limit=100&offset=0
  • Page 2: ?limit=100&offset=100

Cursor-based Pagination (for volatile data)

This method is more robust for data that changes frequently (like issues and entry points) because it prevents items from being skipped or repeated if the underlying data is modified during the pagination process.

• Used for: GET /api/v2/projects/{projectId}/issues, GET /api/v2/projects/{projectId}/entry-points
• Parameters:
  • limit: The maximum number of items per response.
  • nextId: The ID of the last item from the previous response.
  • nextCreatedAt: The creation timestamp of the last item from the previous response..
• How it works: This method is used for data that changes frequently (like issues and entry points) to ensure better performance and consistency. Instead of tracking a numeric offset, you use the details of the last item you received to ask for the "next" set of items.

Example Flow for Fetching All Issues:

1. First Call: Make your initial request with only the limit parameter.
   1. GET /api/v2/projects/{projectId}/issues?limit=100
2. Process the Response: The API returns a list of up to 100 issues. From the very last issue in this list, extract its id and createdAt values.
3. Next Call: Use the extracted values in your next request.
   1. GET /api/v2/projects/{projectId}/issues?limit=100&nextId=...&nextCreatedAt=...
4. Repeat: Continue this process—using the id and createdAt from the last item of each response for the next request—until the API returns an empty list. That's how you'll know you've retrieved all the issues. 🔁

FAQ & API Behavior

This section answers common questions about the data model and API functionality.

How does the projectIssueId work across scans?

The projectIssueId is the key to tracking a unique vulnerability over time. If a new scan finds the exact same vulnerability on the exact same entry point, it will be assigned a new internal ID but will be linked to the same projectIssueId. This allows you to group all instances of a specific vulnerability together.

What's the difference between the name and type fields for an issue?

Currently, there is no difference; they contain the same data (e.g., "CVE-2024-6531" or "Exposed Common File - config.js"). We recommend you use the name field, as the function of these fields could diverge in the future. Both fields should always be present in the response.

Can I get group names or host lists in the main GET /api/v2/projects/{projectId} call?

• Hosts: No, host data is intentionally kept separate for performance. Please use the summary endpoints described in Step 4 of the workflow.
• Group Names: Not at this time. We are considering adding group names to the project details response in a future update. We are also evaluating adding a project_Ids list to the GET /api/v2/me/org/groups response.