> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Setup

> Set up your Postman workspace for testing SCANOSS API endpoints  with authentication and environment configuration.

## Prerequisites

Before setting up your Postman workspace, ensure you have:

* [Postman Desktop App](https://www.postman.com/downloads/) or access to
  [Postman Web](https://web.postman.com/)
* A SCANOSS API key (obtain from your account settings at
  [scanoss.com](https://scanoss.com))
* Familiarity with REST API concepts (HTTP methods, request headers,
  and JSON responses)

## Installing Postman

### Desktop Application

1. Visit [Postman Downloads](https://www.postman.com/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

Alternatively, use Postman in your browser:

1. Visit [web.postman.com](https://web.postman.com/)
2. Sign in or create a free account
3. Start using Postman directly in your browser

## Creating a Workspace

Workspaces help you organise your API collections, environments, and
documentation in one place.

### 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**

![Create Workspace](https://assets.postman.com/postman-docs/create-workspace-v9.jpg)

### Step 2: Create a New Collection

Collections group related API requests together.

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

Environment variables store reusable values such as API keys and base URLs,
allowing you to switch between environments without modifying individual requests.

### 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:

| Variable Name        | Type    | Initial Value             | Current Value             |
| -------------------- | ------- | ------------------------- | ------------------------- |
| `base_url`           | default | `https://api.scanoss.com` | `https://api.scanoss.com` |
| `api_key`            | secret  | *(leave blank)*           | `your-scanoss-api-key`    |
| `vulnerability_path` | default | `/v2/vulnerabilities`     | `/v2/vulnerabilities`     |
| `cryptography_path`  | default | `/v2/cryptography`        | `/v2/cryptography`        |
| `components_path`    | default | `/v2/components`          | `/v2/components`          |

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

Set up authentication at the collection level so that it applies automatically
to all requests within the collection.

### 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**

This configuration automatically adds the `X-Api-Key` header to all requests
in the collection.

### Alternative: Per-Request Header Configuration

To add the header manually to individual requests instead:

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

Organise your requests by API category using 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

For each folder:

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

Verify your configuration with a simple API call.

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

A successful request returns a JSON response similar to the following:

```json theme={null}
{
  "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

**401 Unauthorised**:

* 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

**404 Not Found**:

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

**No Response**:

* 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

To enable environment variable resolution:

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

If a pre-built SCANOSS API collection file or URL has been provided to you:

### 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

Add documentation to each request:

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

Save responses as examples for reference and documentation:

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

Postman automatically synchronises your workspace to the cloud when you are
signed in. To verify:

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

## Next Steps

With your workspace configured, you can proceed to:

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

For detailed examples of API requests, see
[Sending Requests and Reviewing Results](sending-requests-reviewing-results).