openapi: 3.1.0
info:
  title: Postman Secret Scanner API
  description: |
    The Postman Secret Scanner API enables you to manage detected secrets and
    resolve leaked credentials found in your Postman collections, environments,
    and other API assets. The secret scanner automatically detects API keys,
    tokens, passwords, and other sensitive data across your team's workspaces.

    ## Authentication
    All requests require an API key passed in the `x-api-key` header.

    ## Rate Limits
    Standard Postman API rate limits apply.

    ## Availability
    Secret scanning is available on Professional and Enterprise plans.
  version: '1.0.0'
  contact:
    name: Postman Developer Support
    url: https://learning.postman.com/docs/developer/postman-api/intro-api/
    email: help@postman.com
  license:
    name: Postman Terms of Service
    url: https://www.postman.com/legal/terms/
servers:
  - url: https://api.getpostman.com
    description: Postman Production API Server
tags:
  - name: Secret Scanner
    description: Operations for managing detected secrets and leaked credentials.
security:
  - apiKeyAuth: []
paths:
  /secret-scanner/detected-secrets:
    get:
      tags:
        - Secret Scanner
      summary: Postman Get detected secrets
      operationId: getDetectedSecrets
      description: >-
        Gets a list of secrets detected across your team's Postman entities
        (collections, environments, etc.). Returns secret metadata including
        the type of secret, where it was found, and its resolution status.
      parameters:
        - name: cursor
          in: query
          description: Pagination cursor for the next page.
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results to return.
          schema:
            type: integer
            default: 25
            maximum: 50
        - name: since
          in: query
          description: Return secrets detected after this date (ISO 8601).
          schema:
            type: string
            format: date-time
        - name: until
          in: query
          description: Return secrets detected before this date (ISO 8601).
          schema:
            type: string
            format: date-time
        - name: statuses
          in: query
          description: Filter by resolution status (comma-separated).
          schema:
            type: string
            enum: [UNRESOLVED, RESOLVED_FALSE_POSITIVE, RESOLVED_REVOKED, RESOLVED_ACCEPTED_RISK]
        - name: resourceTypes
          in: query
          description: Filter by resource type (comma-separated).
          schema:
            type: string
            enum: [collection, environment, api, request, example, folder]
        - name: workspaceIds
          in: query
          description: Filter by workspace IDs (comma-separated).
          schema:
            type: string
        - name: secretTypes
          in: query
          description: Filter by secret type (comma-separated).
          schema:
            type: string
      responses:
        '200':
          description: Successful response with detected secrets
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DetectedSecret'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      nextCursor:
                        type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /secret-scanner/detected-secrets/{secretId}:
    get:
      tags:
        - Secret Scanner
      summary: Postman Get a detected secret
      operationId: getDetectedSecret
      description: >-
        Gets detailed information about a specific detected secret, including
        where it was found and its resolution history.
      parameters:
        - $ref: '#/components/parameters/SecretIdParam'
      responses:
        '200':
          description: Successful response with secret details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DetectedSecretDetail'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
    put:
      tags:
        - Secret Scanner
      summary: Postman Resolve a detected secret
      operationId: resolveDetectedSecret
      description: >-
        Updates the resolution status of a detected secret. You can mark it
        as revoked, a false positive, or an accepted risk.
      parameters:
        - $ref: '#/components/parameters/SecretIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - resolution
              properties:
                resolution:
                  type: string
                  enum: [RESOLVED_FALSE_POSITIVE, RESOLVED_REVOKED, RESOLVED_ACCEPTED_RISK]
                  description: The resolution status to set
      responses:
        '200':
          description: Successfully resolved secret
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DetectedSecret'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
  /secret-scanner/detected-secrets/{secretId}/locations:
    get:
      tags:
        - Secret Scanner
      summary: Postman Get locations of a detected secret
      operationId: getSecretLocations
      description: >-
        Gets all locations where a detected secret was found across your
        Postman entities.
      parameters:
        - $ref: '#/components/parameters/SecretIdParam'
        - name: cursor
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
            maximum: 50
      responses:
        '200':
          description: Successful response with secret locations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SecretLocation'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
                      nextCursor:
                        type: string
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
  /secret-scanner/secret-types:
    get:
      tags:
        - Secret Scanner
      summary: Postman Get supported secret types
      operationId: getSecretTypes
      description: >-
        Gets a list of all secret types that the scanner can detect, including
        their names and descriptions.
      responses:
        '200':
          description: Successful response with secret types
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SecretType'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitError'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header
      description: Postman API key for authentication.
  parameters:
    SecretIdParam:
      name: secretId
      in: path
      required: true
      description: The detected secret's unique ID.
      schema:
        type: string
  schemas:
    DetectedSecret:
      type: object
      description: A secret detected by the Postman secret scanner.
      properties:
        secretId:
          type: string
          description: The detected secret's unique ID
        secretType:
          type: string
          description: The type of secret detected (e.g., AWS Access Key, GitHub Token)
        resolution:
          type: string
          enum: [UNRESOLVED, RESOLVED_FALSE_POSITIVE, RESOLVED_REVOKED, RESOLVED_ACCEPTED_RISK]
          description: The resolution status of the secret
        workspaceId:
          type: string
          description: The workspace where the secret was found
        workspaceVisibility:
          type: string
          enum: [personal, team, private, public, partner]
        detectedAt:
          type: string
          format: date-time
        resolvedAt:
          type: string
          format: date-time
        resolvedBy:
          type: integer
    DetectedSecretDetail:
      type: object
      description: Detailed information about a detected secret.
      allOf:
        - $ref: '#/components/schemas/DetectedSecret'
        - type: object
          properties:
            secretHash:
              type: string
              description: A hash of the detected secret value (the actual value is not returned)
            occurrences:
              type: integer
              description: Number of locations where this secret was found
            resolutionHistory:
              type: array
              items:
                type: object
                properties:
                  resolution:
                    type: string
                  resolvedBy:
                    type: integer
                  resolvedAt:
                    type: string
                    format: date-time
    SecretLocation:
      type: object
      description: A location where a secret was detected.
      properties:
        resourceType:
          type: string
          enum: [collection, environment, api, request, example, folder]
          description: The type of resource containing the secret
        resourceId:
          type: string
          description: The resource's unique ID
        resourceName:
          type: string
          description: The resource name
        workspaceId:
          type: string
        parentResourceId:
          type: string
          description: The parent resource ID (e.g., collection ID for a request)
        isActive:
          type: boolean
          description: Whether the secret is still present at this location
        detectedAt:
          type: string
          format: date-time
        url:
          type: string
          format: uri
          description: A link to the resource in Postman
    SecretType:
      type: object
      description: A type of secret that the scanner can detect.
      properties:
        name:
          type: string
          description: The display name of the secret type
          example: AWS Access Key ID
        slug:
          type: string
          description: The machine-readable identifier
          example: aws-access-key-id
        description:
          type: string
          description: A description of the secret type
  responses:
    BadRequestError:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
    UnauthorizedError:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
    ForbiddenError:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
    NotFoundError:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string
    RateLimitError:
      description: Too many requests - rate limit exceeded
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              message:
                type: string
    InternalServerError:
      description: An unexpected error occurred on the server
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                  message:
                    type: string