postman-cs/Postman Onboarding: AWS Spec Discovery

Discover AWS-hosted API specs and expose a spec path for Postman onboarding. Part of the Postman API Onboarding suite.

Trust Signals

Scorecard Score: not yet scored
Maintenance Recency: Stale
License: None

Inputs

name	description	required	default
aws-region	AWS region used to resolve API Gateway, AppSync, SNS, EventBridge, Lambda, and other discovery providers.	yes	—
gateway-id	Optional known API Gateway ID for this service. Use this when you want to bypass broader account discovery.	no	""
stage	Optional API Gateway stage override (for example prod or staging).	no	""
expected-account-id	Optional AWS account ID that must match sts:GetCallerIdentity before export. Mismatch fails closed with a sanitized error.	no	""
expected-partition	Optional AWS partition (aws, aws-us-gov, or aws-cn) that must match the caller identity ARN before export. Mismatch fails closed with a sanitized error.	no	""
expected-region	Optional AWS region that must exactly match aws-region before discovery or export. Mismatch fails closed.	no	""
spec-path	Optional explicit path to a repository specification relative to repo-root. When set, resolution uses this contract and skips same-tier auto-selection.	no	""
service-root	Optional monorepo service root relative to repo-root. Scopes Backstage entities and repository contract inventory to that directory.	no	""
remote-fetch-allowlist-json	Optional JSON array of exact remote-fetch allowlist entries ({"hostname","pathPrefix"} or {"host","path"}). Absent or empty denies all remote spec fetches (Backstage, SSM, SNS).	no	""
terraform-state-paths-json	Optional JSON array of repo-relative local Terraform state/output artifact paths (for example terraform.tfstate). Default []. .tfstate is never auto-discovered; only listed paths are read. Remote Terraform state remains forbidden.	no	[]
output-dir	Directory under the repository root where generated specs are written.	no	discovered-specs
postman-api-key	Optional service-account PMAK used to mint or re-mint a postman-access-token for telemetry enrichment (account_type). Not used for any AWS or Postman asset operation.	no	""
postman-access-token	Optional Postman service-account access token, used only to enrich anonymous telemetry with the session account_type. When omitted, postman-api-key alone can mint one for the same purpose. Not used for any AWS or Postman asset operation.	no	""

Outputs

name	description
resolution-json	JSON resolution result describing status, source type, confidence, and evidence.
resolution-status	Resolution status: resolved or unresolved.
source-type	Resolved source type: repo-spec, gateway-export, appsync-schema, appsync-event-api, eventbridge-schema, eventbridge-surface, cfn-embedded, glue-schema, bedrock-action-group, alb-listener-rule, sns-contract, ssm-registry, lambda-url-export, lambda-event-source, verified-permissions-schema, step-functions-asl, manual-review, or discover-many.
mapping-confidence	Numeric confidence score for selected service candidate.
spec-path	Path to resolved or generated specification when available.
spec-files-json	Optional single-line JSON inventory of authoritative multi-file definition members (schemaVersion 1). Empty for single-file results, unresolved runs, discover-many top-level outputs, derived OpenAPI, and deterministic GraphQL/Smithy composition.
gateway-id	Resolved API Gateway ID when available.
service-name	Resolved service name.
services-json	Legacy discover-many output: JSON array of exported services.
service-count	Legacy discover-many output: number of exported services.
export-summary-json	discover-many summary JSON with attempted/exported/failed/skipped counts.
candidates-json	JSON array of top candidates when resolution is ambiguous.
provider-type	Provider that resolved the spec: api-gateway, appsync, appsync-events, eventbridge-schemas, eventbridge, cloudformation, glue, bedrock-action-group, alb-listener-rule, sns, ssm, lambda-url, lambda-event-source, verified-permissions, or step-functions.
spec-format	Format of the resolved spec: openapi-yaml, openapi-json, graphql-sdl, graphql-introspection-json, asyncapi-yaml, asyncapi-json, json-schema, postman-collection, smithy, avro, protobuf, wsdl, or mcp-json.
contract-origin	SNS contract provenance when available: repo-asyncapi, repo-json-schema, generated-asyncapi, ssm-content, ssm-url, catalog-url, eventbridge-derived, code-derived, or manual-review.
contract-metadata-path	Path to SNS resolution metadata sidecar when available.
variant-count	Number of SNS delivery variants discovered when available.
derived-openapi-path	Path to the canonical derived OpenAPI JSON sidecar when available.
derived-openapi-version	OpenAPI version of the derived sidecar when available.
derived-openapi-completeness	Derived OpenAPI completeness: full or partial.
derived-openapi-format	Format of the derived OpenAPI sidecar, currently openapi-json.
derived-openapi-evidence-json	JSON array of evidence entries explaining derived OpenAPI quality and limitations.
narrowing-strategy	Progressive narrowing tier applied to API Gateway candidates (iac-fingerprint, cfn-correlation, tag-prefilter, naming-heuristic), or none when no tier matched.