Workspace Setup

​

Prerequisites

• Postman Desktop App or access to Postman Web
• A SCANOSS API key (obtain from your account settings at scanoss.com)
• Familiarity with REST API concepts (HTTP methods, request headers, and JSON responses)

​

Installing Postman

​

Desktop Application

1. Visit Postman Downloads
2. Download the installer for your platform:
   • Windows: .exe installer
   • macOS: .dmg file
   • Linux: .tar.gz or snap package
3. Run the installer and follow the on-screen instructions

​

Web Version

1. Visit web.postman.com
2. Sign in or create a free account
3. Start using Postman directly in your browser

​

Creating a Workspace

​

Step 1: Create a New Workspace

1. Open Postman
2. Click Workspaces in the top left
3. Click Create Workspace
4. Enter the workspace details:
   • Name: SCANOSS API Testing
   • Summary: Workspace for testing SCANOSS API endpoints
   • Visibility: Select Personal for individual use or Team for shared access
5. Click Create Workspace

​

Step 2: Create a New Collection

1. In your workspace, click Collections in the left sidebar
2. Click + or Create a collection
3. Name it SCANOSS API
4. Add a description: Collection of SCANOSS API endpoints for security intelligence, cryptography analysis, and component search
5. Click Create

​

Setting Up Environment Variables

​

Create an Environment

1. Click Environments in the left sidebar
2. Click + or Create Environment
3. Name it SCANOSS Production
4. Add the following variables:

5. Click Save

​

Variable Types Explained

• default: Visible to collaborators. Use for non-sensitive configuration values.
• secret: Hidden from collaborators. Use for API keys and passwords.

​

Initial Value vs Current Value

• Initial Value: Shared with team members and synchronised to the Postman cloud. Do not store sensitive credentials here when sharing a collection.
• Current Value: Stored locally on your machine only; never synchronised. Use this field for your actual API key.

Best Practice: When working alone, you may populate both the Initial and Current values with your API key. When sharing a collection with others, leave the Initial Value blank and enter your API key in the Current Value field only.

​

Configuring Collection Authorisation

​

Step 1: Open Collection Settings

1. Click on your SCANOSS API collection
2. Click the … (three dots) menu
3. Select Edit
4. Go to the Authorization tab

​

Step 2: Configure API Key Authentication

Terminology note: X-Api-Key is the HTTP header name sent with each request. api_key is the Postman environment variable that holds your key value.

1. Type: Select API Key from the dropdown
2. Configure the key:
   • Key: X-Api-Key
   • Value: {{api_key}} (references the environment variable)
   • Add to: Header
3. Click Save

​

Alternative: Per-Request Header Configuration

1. Open any request and go to the Headers tab
2. Add a new header:
   • Key: X-Api-Key
   • Value: {{api_key}}

​

Creating Request Folders

​

Step 1: Create Folders

1. Hover over your SCANOSS API collection
2. Click … → Add folder
3. Create the following folders:
   • Vulnerability API
   • Cryptography API
   • Component Search
   • Dependency Decoration
   • Raw Output

Note: The Vulnerability API folder corresponds to what the SCANOSS platform also refers to as the Security API in some contexts.

​

Step 2: Add Descriptions

1. Click … → Edit
2. Add a description:
   • Vulnerability API: Endpoints for retrieving vulnerability data and CPEs
   • Cryptography API: Endpoints for cryptographic algorithm analysis
   • Component Search: Endpoints for searching and retrieving component information
   • Dependency Decoration: Endpoints for enriching dependency data with SCANOSS intelligence
   • Raw Output: Endpoints returning raw scan output for direct fingerprint analysis

​

Testing Your Setup

​

Create a Test Request

1. Right-click the Vulnerability API folder
2. Select Add request
3. Name it Get Component CPEs - Test
4. Configure the request:
   • Method: GET
   • URL: {{base_url}}{{vulnerability_path}}/cpes/component?purl=pkg:github/scanoss/engine&requirement=>=5.0.0
5. Click Send

​

Expected Response

{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "requirement": ">=5.0.0",
    "version": "5.0.0",
    "cpes": ["cpe:2.3:a:scanoss:engine:1.0.0:*:*:*:*:*:*:*"]
  },
  "status": {
    "status": "SUCCESS",
    "message": "CPEs Successfully retrieved"
  }
}

​

Troubleshooting

• Verify that the api_key environment variable contains a valid API key
• Confirm that the correct environment is selected (dropdown in the top right)
• Check the Headers tab to confirm the X-Api-Key header is present

• Verify the request URL is correct
• Check that all environment variables are populated
• Ensure the base_url value does not have a trailing slash

• Check your internet connection
• Verify that the SCANOSS API is reachable
• Open the Postman Console for detailed error output (View → Show Postman Console)

​

Selecting the Active Environment

1. Locate the environment dropdown in the top right corner of Postman
2. Click the dropdown (it may display No Environment)
3. Select SCANOSS Production
4. Confirm the environment name is shown in the dropdown

​

Importing a SCANOSS Collection

​

Import from Link

1. Click Import in the top left
2. Select the Link tab
3. Paste the collection URL
4. Click Continue → Import

​

Import from File

1. Click Import in the top left
2. Select the File tab, or drag and drop the file into the import window
3. Select the collection JSON file
4. Click Import

​

Workspace Organisation Tips

​

Naming Conventions

• Requests: Use descriptive names such as Get Component Vulnerabilities rather than Request 1
• Folders: Group by API category or functional workflow
• Environments: Include the target environment in the name (e.g., SCANOSS Production, SCANOSS Staging)

​

Documentation

1. Select a request
2. Click the Documentation icon (📄) or tab
3. Add:
   • Description: What the endpoint does
   • Parameters: Explanation of query parameters and their expected values
   • Example Response: A sample successful response

​

Using Examples

1. After receiving a response, click Save Response
2. Name the example (e.g., Successful Response or Component Not Found)
3. Saved examples appear in the right sidebar and in the collection documentation

​

Collection Variables vs Environment Variables

​

When to Use Collection Variables

• Values that are specific to the collection and do not vary between environments
• Shared path segments or common parameters
• Mock server URLs

​

When to Use Environment Variables

• Values that change between environments (Production, Staging, Development)
• API keys and authentication tokens
• Base URLs that differ per environment

​

Setting Collection Variables

1. Click on your collection
2. Go to the Variables tab
3. Add variables, for example:
   • version: v2
   • timeout: 30000

​

Best Practices

1. Use environment variables for credentials: Never hardcode API keys directly in request URLs or headers.
2. Organise requests into folders: Group related endpoints together to improve navigability.
3. Document each request: Include a description, parameter definitions, and a sample response for every request.
4. Save response examples: Capture examples for both success and error scenarios.
5. Export and version your collections: Regularly export collection and environment JSON files and store them in version control.
6. Protect sensitive data when sharing: Ensure the Initial Value of secret variables is blank before exporting or sharing a collection.
7. Write test scripts: Add Postman test scripts to validate response status codes, structure, and field values automatically.

​

Backing Up Your Workspace

​

Export Collection

1. Click … on your collection
2. Select Export
3. Choose Collection v2.1 (recommended)
4. Save the JSON file

​

Export Environment

1. Click … on your environment
2. Select Export
3. Save the JSON file
4. Note: Secret variable values are not included in exports for security reasons.

​

Cloud Synchronisation

1. Check the sync icon in the header
2. Confirm it shows Synced or a checkmark

​

Next Steps

1. Add requests: Create requests for all SCANOSS API endpoints
2. Test endpoints: Send requests and review the responses
3. Write test scripts: Validate response status codes and payloads
4. Run collection workflows: Use the Collection Runner to execute requests sequentially
5. Generate documentation: Publish API documentation using Postman’s built-in documentation tools