S4E provides an official Postman collection for exploring and testing the API interactively. This page covers importing the collection, configuring your environment, and using it effectively.

Importing the Collection

Option 1 --- Download and Import

1. Download the collection file from the S4E platform:

   • Log in to S4E and navigate to Settings > API > Postman Collection.
   • Click Download Collection to get the S4E-API.postman_collection.json file.

2. Open Postman and click Import in the top-left corner.

3. Drag the downloaded JSON file into the import dialog, or click Upload Files and select it.

4. Click Import to add the collection to your workspace.

Option 2 --- Import via URL

In Postman, click Import, select the Link tab, and paste:

https://api.s4e.io/api/docs/postman-collection.json

Click Continue and then Import.

Setting Up the Environment

The collection uses Postman environment variables for configuration. Create an environment with the following variables:

Creating the Environment

1. In Postman, click Environments in the left sidebar.
2. Click + to create a new environment.
3. Name it S4E Development (or S4E Production).
4. Add the following variables:

1. Click Save.
2. Select the environment from the dropdown in the top-right corner of Postman.

Collection Structure

The collection is organized into folders that mirror the API documentation:

S4E API Collection
  |-- Authentication
  |   |-- Login
  |   |-- Refresh Token
  |   |-- Logout
  |
  |-- Assets
  |   |-- List Assets
  |   |-- Create Asset
  |   |-- Get Asset Details
  |   |-- Update Asset
  |   |-- Delete Asset
  |   |-- Bulk Import
  |   |-- Verify Asset
  |
  |-- Scans
  |   |-- Create Scan
  |   |-- List Scans
  |   |-- Get Scan Details
  |   |-- Get Scan Status
  |   |-- Cancel Scan
  |   |-- Get Scan Results
  |
  |-- Findings
  |   |-- List Findings
  |   |-- Get Finding Details
  |   |-- Update Finding Status
  |   |-- Export Findings
  |   |-- Finding Statistics
  |
  |-- Actions
  |   |-- List Actions
  |   |-- Create Action
  |   |-- Trigger Action
  |   |-- Get Execution Details
  |
  |-- Playbooks
  |   |-- List Playbooks
  |   |-- Create Playbook
  |   |-- Run Playbook
  |   |-- Get Execution Status
  |
  |-- Webhooks
  |   |-- Create Webhook
  |   |-- List Webhooks
  |   |-- Test Webhook
  |   |-- Delete Webhook
  |
  |-- API Keys
      |-- List Keys
      |-- Create Key
      |-- Revoke Key

Authentication Setup

Using API Key (Recommended)

The collection's Authorization tab is pre-configured to use the api_key environment variable. Every request inherits this configuration automatically.

1. Click on the collection name.
2. Go to the Authorization tab.
3. Verify the type is set to Bearer Token with value {{api_key}}.

Using Session Token

To use session-based authentication:

1. Run the Login request in the Authentication folder.
2. The pre-request script automatically saves the token to the token environment variable.
3. Switch the collection authorization to use {{token}} instead of {{api_key}}.

Pre-Request Scripts

The collection includes pre-request scripts that automate common setup tasks:

Auto-Authentication

The Login request includes a test script that saves the session token:

if (pm.response.code === 200) {
    var response = pm.response.json();
    pm.environment.set("token", response.data.token);
    console.log("Token saved to environment.");
}

Dynamic Variables

Some requests capture response data for use in subsequent requests:

// In "Create Asset" test script
if (pm.response.code === 201) {
    var response = pm.response.json();
    pm.environment.set("asset_id", response.data.id);
}

Using the Collection Runner

Run multiple requests in sequence for batch testing:

1. Click Runner in the bottom toolbar (or right-click the collection and select Run collection).
2. Select the folder or requests to run.
3. Set the iteration count and delay between requests.
4. Click Run.

Suggested Test Sequences

Full lifecycle test:

1. Create Asset
2. Trigger Scan
3. Get Scan Status (poll until completed)
4. List Findings
5. Export Findings

Action test:

1. List Actions
2. Trigger Action
3. Get Execution Details

Exporting Results

After running the collection:

1. Click Export Results in the runner view.
2. Choose the format (JSON or HTML report via Newman).
3. Save or share the results with your team.

Sharing with Your Team

Postman Workspace

1. Create a Team Workspace in Postman.
2. Move the collection and environment to the workspace.
3. Invite team members to the workspace.

Exporting as File

1. Right-click the collection and select Export.
2. Choose Collection v2.1 format.
3. Share the JSON file with your team.

Keeping the Collection Updated

The S4E Postman collection is updated with each API release. To update:

1. Re-import the collection from the download URL.
2. Postman will detect the existing collection and offer to replace or merge it.
3. Select Replace to get the latest version.

Next Steps

• cURL Examples for command-line API usage.
• API Reference for the complete endpoint documentation.
• Authentication for detailed auth setup.