saw-api-target-configuration

name	saw-api-target-configuration
description	Configure Snyk API & Web API targets. Use ONLY when the user explicitly provides or mentions an OpenAPI/Swagger schema, a Postman collection, or explicitly says "API target". Do NOT use for generic "add target" or "create target" requests — use saw-web-target-configuration instead.

API Target Configuration Skill (Snyk API & Web)

Configure API targets for Snyk API & Web security scanning. For web application targets with authentication, use the saw-web-target-configuration skill instead.

When you finish adding/configuring a target, always summarize it with a table, and include a link to the target on Snyk API & Web. Use the Snyk API & Web app URL https://plus.probely.app. Include a column if you added extra hosts or not and in case you did, which ones.

Credentials Management — Recommended (Used by Default)

Use the credential manager for sensitive values (API keys, Bearer tokens, Basic Auth passwords, etc.) by default. Store values via probely_create_credential with is_sensitive=True and use the returned uri (e.g. credentials://xxxx) in the API. If the user explicitly declines, inline values are allowed.

Non-sensitive values (non-secret header names, environment labels) can be passed inline.

Shared Credentials Across Multiple Targets

When configuring multiple targets that use the same credentials, the credential may already exist in the credential manager from a previous target. Since sensitive (obfuscated) values cannot be read back, the agent cannot verify whether it matches — this causes a new credential entry per target, polluting the credential manager.

Rule: When multiple targets share the same credential and it already exists with is_sensitive=True, prompt the user to deobfuscate it (update to is_sensitive=False via probely_update_credential) so it can be read back and reused across targets. Inform the user why deobfuscation is needed.

Workflow for shared credentials:

1. Create the credential normally with is_sensitive=True for the first target.
2. When a subsequent target needs the same credential, find the existing one via probely_list_credentials.
3. If the existing credential is sensitive (is_sensitive=true), prompt the user: "The credential '' is obfuscated. To reuse it across multiple targets, it needs to be deobfuscated. Would you like to proceed?"
4. If the user agrees, update it: probely_update_credential(credentialId, is_sensitive=False).
5. Reuse the same credential uri for the new target.

Pattern:

cred = probely_create_credential(
  name="<target_name> - <description>",   # e.g. "MyAPI - Bearer token"
  value="the_actual_secret_value",
  is_sensitive=True                       # always sensitive by default
)
# cred["uri"] → "credentials://xxxx"

Credential URIs: Use the format credentials://<credential_id> (e.g., credentials://4DY4qGohso1r). Get credential URIs from probely_list_credentials or probely_create_credential. Do NOT use template syntax like {{cred-name}}.

API Onboarding Workflow

When the user wants to scan an API, follow this workflow:

Target name: Use the name the user provides. If the user does not specify a name, use the API name derived from the schema title, Postman collection name, or the domain. Example: no name given for https://api.example.com → Example API. A default label (e.g. "Agentic") is auto-applied from the MCP server config — do NOT look up, create, or pass labels manually unless the user explicitly asks for additional labels.

Step 1: Obtain API Schema

Ask the user to provide one of the following (they are alternatives):

1. OpenAPI/Swagger schema (URL or JSON/YAML file)
2. Postman collection (URL or JSON file)

If neither is available, offer to generate an OpenAPI schema by:

• Analyzing the codebase for API endpoints
• Looking for existing route definitions (Express, FastAPI, Flask, Django, etc.)
• Creating a basic OpenAPI 3.0 schema from discovered endpoints

Step 2: Create API Target

For Postman collections:

probely_create_api_target_from_postman(
  name: "API Name",
  target_url: "https://api.example.com",
  postman_collection_url: "https://..." OR postman_collection_json: {...},
  desc: "Description",
  labels: ["api", "project-name"]
)

For OpenAPI schemas: Validate the schema file before uploading it. If the schema has violations fix them first.

probely_create_api_target_from_openapi(
  name: "API Name",
  target_url: "https://api.example.com",
  openapi_schema_url: "https://..." OR openapi_schema_json: {...},
  desc: "Description",
  labels: ["api", "project-name"]
)

Troubleshooting Target Creation

When creating a target, the API may return warnings. Handle them as follows:

• "Target already exists" — The Probely API warns when a target with the same URL already exists. Do NOT treat this as an error. Inform the user that a target with this URL already exists and ask whether they want to proceed with creating a duplicate or use the existing target instead. If they choose to create a duplicate, use the allow_duplicate=True parameter. If they choose the existing one, use probely_list_targets(search="<url>") to find it.
• "Target didn't match server URL from API schema" — This warning appears when the target_url passed during creation doesn't match any servers[].url entry in the OpenAPI schema. Do NOT treat this as an error. Inform the user about the mismatch and ask whether the target URL is correct. Common causes: the schema lists http://localhost:3000 but the target URL is the production domain, or the schema has a different base path. The target is still created — the scanner will use the provided target URL.
• Reachability errors — If target creation fails because the target is unreachable or the domain cannot be resolved, ask the user whether you should retry with skip_reachability_check=True. Only retry after the user explicitly agrees.

Creating Duplicate Targets

To create a duplicate target (same URL as existing target), use allow_duplicate=True. This is useful when you want multiple targets for the same URL with different configurations (e.g., different authentication methods, different test scenarios):

# For OpenAPI targets:
probely_create_api_target_from_openapi(
    name="MyAPI - Different Auth Method",
    target_url="https://api.example.com",  # Same URL as existing target
    openapi_schema_url="https://...",
    allow_duplicate=True,  # Bypass duplicate URL check
)

# For Postman targets:
probely_create_api_target_from_postman(
    name="MyAPI - Test Scenario 2",
    target_url="https://api.example.com",  # Same URL as existing target
    postman_collection_url="https://...",
    allow_duplicate=True,  # Bypass duplicate URL check
)

Step 3: Configure API Authentication (if needed)

If the API requires authentication:

• Ask user for auth type (API key/Bearer token in headers, session cookies, or HTTP Basic Auth)
• By default, store sensitive values via probely_create_credential and use the credential URI in the header/cookie value. If the user explicitly declines, inline values are allowed.
• Use probely_update_target with the headers and/or cookies parameters

IMPORTANT: There are two different ways to configure headers/cookies in Probely:

1. General custom headers/cookies (via probely_update_target headers/cookies parameters): Sent with every scan request, NOT used for authentication. Simple structure: {"name": "...", "value": "..."}

2. API authentication headers/cookies (via probely_update_target api_auth_headers/api_auth_cookies parameters): Used for authentication. Requires full structure with authentication flags. The tool automatically configures api_scan_settings.

Authentication Method 1: HTTP Basic Auth

Use probely_update_target with basic_auth_username and basic_auth_password parameters:

# When user opts in to credentials management:
username_cred = probely_create_credential(name="<target_name> - username", value="api-user", is_sensitive=False)
password_cred = probely_create_credential(name="<target_name> - password", value="secret123", is_sensitive=True)

probely_update_target(
  targetId=targetId,
  basic_auth_username=username_cred["uri"],  # e.g., "credentials://4DY4qGohso1r"
  basic_auth_password=password_cred["uri"]   # e.g., "credentials://3B7JRXx6vbrD"
)

# When user does NOT opt in:
probely_update_target(
  targetId=targetId,
  basic_auth_username="api-user",
  basic_auth_password="secret123"
)

Authentication Method 2: Static Headers/Cookies (API Keys, Bearer Tokens, Session Cookies)

Use probely_update_target with api_auth_headers and/or api_auth_cookies parameters:

# Example 1: API Key Header Authentication
# When user opts in to credentials management:
api_key_cred = probely_create_credential(name="<target_name> - API key", value="sk-live-xxx", is_sensitive=True)

probely_update_target(
  targetId=targetId,
  api_auth_headers=[{
    "name": "X-API-Key",
    "value": api_key_cred["uri"],  # e.g., "credentials://3hBVSPfBbcaH"
    "value_is_sensitive": False,
    "allow_testing": False,
    "authentication": True,
    "authentication_secondary": False
  }]
)

# When user does NOT opt in:
probely_update_target(
  targetId=targetId,
  api_auth_headers=[{
    "name": "X-API-Key",
    "value": "sk-live-xxx",  # Inline value
    "value_is_sensitive": False,
    "allow_testing": False,
    "authentication": True,
    "authentication_secondary": False
  }]
)

# Example 2: Bearer Token Authentication
token_cred = probely_create_credential(name="<target_name> - Bearer token", value="eyJhb...", is_sensitive=True)

probely_update_target(
  targetId=targetId,
  api_auth_headers=[{
    "name": "Authorization",
    "value": f"Bearer {token_cred['uri']}",  # Note: prefix with "Bearer "
    "value_is_sensitive": False,
    "allow_testing": False,
    "authentication": True,
    "authentication_secondary": False
  }]
)

# Example 3: Session Cookie Authentication
cookie_cred = probely_create_credential(name="<target_name> - session cookie", value="secret-token", is_sensitive=True)

probely_update_target(
  targetId=targetId,
  api_auth_cookies=[{
    "name": "session",
    "value": cookie_cred["uri"],  # e.g., "credentials://32otBAEip2Km"
    "value_is_sensitive": False,
    "allow_testing": False,
    "authentication": True,
    "authentication_secondary": False
  }]
)

# Example 4: Combined Headers and Cookies
probely_update_target(
  targetId=targetId,
  api_auth_headers=[{
    "name": "X-Secret-Header",
    "value": "credentials://xxx",
    "value_is_sensitive": False,
    "allow_testing": False,
    "authentication": True,
    "authentication_secondary": False
  }],
  api_auth_cookies=[{
    "name": "secret-cookie",
    "value": "credentials://yyy",
    "value_is_sensitive": False,
    "allow_testing": False,
    "authentication": True,
    "authentication_secondary": False
  }]
)

Note: The probely_update_target tool automatically sets api_scan_settings with:

• api_login_enabled: True
• api_login_method: "headers_or_cookies"
• api_headers_cookies_login_enabled_secondary: False