Multipage preference

Draft ECMA-xxx

1st edition / December 8, 2026

Transparency Exchange API Specification

About this Standard

The document at https://tc54.org/ecmaXXX/ is the most accurate and up-to-date Transparency Exchange API specification.

This document is available as a single page and as multiple pages.

Contributing to this Standard

This Standard is developed on GitHub with the help of the OWASP community. There are a number of ways to contribute to the development of this Standard:

Refer to the Colophon for more information on how this document is created.

Introduction

The TEA API is created to support automation of the software supply chain. Upstream vendors and open source projects can use this standard to keep downstream users up to date with transparency artifacts such as, but not limited to, bill of materials, VEX files, attestations and much more.

This specification defines a standard, format agnostic, API for the exchange of product related artifacts, like BOMs, between systems. The work includes:

System and tooling implementors are encouraged to adopt this API standard for sending and receiving transparency artifacts between systems. This will enable more widespread "out of the box" integration support in the BOM ecosystem. In addition, it will support automatic delivery of upstream vulnerability assessments, such as VEX files.

Data model

The data model is flexible to be able to handle many different use cases, from mobile applications and Open Source software to complex bundles of hardware sold in stores.

  • TEA Product Release: The primary entry point. The Transparency Exchange Identifier (TEI) resolves to one or more Product Releases, normally one. A Product Release belongs to a TEA Product.
  • TEA Product: A higher-level object that groups a set of Product Releases for a product line or family. Products can be discovered and browsed.
  • TEA Component: Represents a component lineage. A Component is a collection of Component Releases.
  • TEA Release: A Component Release object. Each Component Release has its own TEA Collection.
  • TEA Collection: A versioned list of artifacts for a specific Component Release or Product Release. Collections are versioned to indicate changes, e.g., an updated VEX or corrected SBOM.
  • TEA artifacts: Files associated with a Collection. A single TEA artifact can appear in multiple Collections.

Artifacts available using the API

The Transparency Exchange API (TEA) supports retrieval of a set of transparency exchange artifacts. The API itself is not restricting the types of the artifacts published. A few examples:

xBOM

Bill of materials for any type of component and service are supported. This includes, but is not limited to, SBOM, HBOM, AI/ML-BOM, SaaSBOM, and CBOM. The API provides a BOM format agnostic way of publishing, searching, and retrieval of xBOM artifacts.

CDXA

Standards and requirements along with attestations to those standards and requirements are captured and supported by CycloneDX Attestations (CDXA). Much like xBOM, these are supply chain artifacts that are captured allowing for consistent publishing, searching, and retrieval.

VDR/VEX

Vulnerability Disclosure Reports (VDR) and Vulnerability Exploitability eXchange (VEX) are supported artifact types. Like the xBOM element, the VDR/VEX support is format agnostic. However, CSAF has its own distribution requirements that may not be compatible with APIs. Therefore, the initial focus will be on CycloneDX (VDR and VEX) and OpenVEX.

CLE

Product lifecycle events are communicated through the ECMA-428 Common Lifecycle Enumeration standard. This includes product rebranding, repackaging, mergers and acquisitions, and product milestone events such as end-of-life and end-of-support.

Inclusion of CLE is optional and it may be introduced on the following levels:

  • TEA Product
  • TEA Component
  • TEA Product Release
  • TEA Component Release

If CLE is included, it is the responsibility of the TEA implementation to ensure consistency of CLE events across the TEA Product and its releases and similarly across the TEA Component and its releases.

Background

The Transparency Exchange API standard is created by OWASP CycloneDX in ECMA TC54 - Software and system transparency. TEA is managed by ECMA TC54 TG1. TEA depends on and is developed alongside with related ECMA standards, such as:

For more information of these and releated standards, visit https://tc54.org

1 Scope

This Standard defines the Transparency Exchange API (TEA), a format-agnostic protocol for the exchange of software, hardware and system transparency artefacts—including, but not limited to, Bills of Materials (xBOMs), attestations, vulnerability disclosure documents, and lifecycle events—between publishers and consumers.

The Standard covers:

The Standard does not define the internal format of the transparency artefacts themselves; those are defined by their respective standards (e.g. CycloneDX, SPDX, OpenVEX, CSAF, CDXA).

2 Conformance

This Standard defines two conformance classes: TEA server and TEA client. An implementation may conform to either or both.

A conformant TEA server shall:

A conformant TEA client shall:

The verbal forms in this Standard follow ISO/IEC Directives, Part 2: shall and shall not indicate requirements; should and should not indicate recommendations; may and need not indicate permission; and can and cannot indicate possibility or capability. The verbal form must is used only for external constraints and does not express a requirement of this Standard.

3 Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

ECMA-424, CycloneDX Bill of Materials Specification.
https://ecma-international.org/publications-and-standards/standards/ecma-424/

ECMA-427, Package-URL (PURL) specification.
https://ecma-international.org/publications-and-standards/standards/ecma-427/

ECMA-428, Common Lifecycle Enumeration (CLE).
https://ecma-international.org/publications-and-standards/standards/ecma-428/

IETF RFC 3339, Date and Time on the Internet: Timestamps.
https://www.rfc-editor.org/info/rfc3339/

IETF RFC 3986, Uniform Resource Identifier (URI): Generic Syntax
https://www.rfc-editor.org/info/rfc3986/

IETF RFC 6749, The OAuth 2.0 Authorization Framework.
https://www.rfc-editor.org/info/rfc6749/

IETF RFC 6750, The OAuth 2.0 Authorization Framework: Bearer Token Usage.
https://www.rfc-editor.org/info/rfc6750/

IETF RFC 7617, The 'Basic' HTTP Authentication Scheme.
https://www.rfc-editor.org/info/rfc7617/

IETF RFC 8615, Well-Known Uniform Resource Identifiers (URIs).
https://www.rfc-editor.org/info/rfc8615/

IETF RFC 9110, HTTP Semantics.
https://www.rfc-editor.org/info/rfc9110/

IETF RFC 9111, HTTP Caching.
https://www.rfc-editor.org/info/rfc9111/

IETF RFC 9525, Service Identity in TLS.
https://www.rfc-editor.org/info/rfc9525/

IETF RFC 9530, Digest Fields.
https://www.rfc-editor.org/info/rfc9530/

IETF RFC 9562, Universally Unique IDentifiers (UUIDs).
https://www.rfc-editor.org/info/rfc9562/

OpenAPI Specification 3.1.1
https://spec.openapis.org/oas/v3.1.1.html

IETF draft-handrews-json-schema-01, JSON Schema: A Media Type for Describing JSON Documents.
https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-01

IETF draft-handrews-json-schema-validation-01, JSON Schema Validation: A Vocabulary for Structural Validation of JSON.
https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-validation-01

SemVer 2.0.0
https://semver.org/spec/v2.0.0.html

4 Terms and definitions

4.1 Terms

For the purposes of this Standard, the following terms and definitions apply:

4.1.1 Attestation

machine-readable statement containing facts, evidence, or testimony

4.1.2 Authentication

authn

process of verifying the identity of a principal

4.1.3 Authorization

authz

process of determining what a verified principal is permitted to do

4.1.4 Collection

versioned list of the TEA Artifacts of one Component Release or one Product Release

Note

A Collection has the same UUID as the release to which it belongs. A change to its content produces a new version, which records the reason for the change.

4.1.5 Compliance document

document describing the compliance, certification or regulatory status of a Component, for example a SOC 2 report

Note

A compliance document is published as a TEA Artifact of a Component Release. The Component or Component Release is marked with the COMPLIANCE_DOCUMENT identifier type so that it can be discovered.

4.1.6 Component

software or hardware item whose successive versions are Component Releases

Note

A Product Release can reference Components and specific Component Releases.

4.1.7 Component Release

specific version of a Component

Note

Each Component Release has its own Collection.

4.1.8 Discovery document

JSON document served at /.well-known/tea on the host named by the domain name of a TEI, listing the TEA server endpoints for that domain and the API versions they support

4.1.9 Product

item sold, distributed or otherwise delivered under one name

4.1.10 Product Release

specific version of a Product that can be acquired or downloaded

4.1.11 Software bill of materials

SBOM

structured inventory of the software components of a product, with their versions, identifiers and dependencies

4.1.12 TEA Artifact

security-related document, such as an SBOM, a VEX document or an attestation, published in one or more formats and identified by a UUID and a version

4.1.13 TEA client

software that retrieves information from a TEA server using the API defined in this Standard

4.1.14 TEA server

server that implements the API defined in this Standard

4.1.15 Transparency Exchange Identifier

TEI

URI of the form tei://<domain-name>/<type>/<unique-identifier> that identifies one or more Product Releases

Note

The domain name of a TEI is used to locate the TEA server; see Clause 5.

4.1.16 Vendor

party that publishes TEIs for its Product Releases

Note

A vendor can be a commercial company or an open source project.

4.1.17 Vulnerability Exploitability eXchange document

VEX document

document stating, for a product, the exploitability status of known vulnerabilities

Note

A VEX document states, for example, whether a vulnerability affects the product, does not affect it, or is mitigated.

4.2 Acronyms and abbreviations

For the purposes of this Standard, the following abbreviations apply:

Table 1: Acronyms & abbreviations
Abbreviation  
API Application Programming Interface
CPE Common Platform Enumeration, a naming scheme for IT products and platforms, usable as an identifier type
CSAF Common Security Advisory Framework, an OASIS standard for machine-readable security advisories
EAN International Article Number (formerly European Article Number); an EAN-13 or EAN-8 number is a GTIN of 13 or 8 digits
GTIN Global Trade Item Number, the GS1 identification key for trade items, of 8, 12, 13 or 14 digits
SBOM Software bill of materials
TEA Transparency Exchange API
TEI Transparency Exchange Identifier
UPC Universal Product Code; a UPC-A number is a GTIN of 12 digits
UUID Universally Unique Identifier
VDR Vulnerability Disclosure Report
VEX Vulnerability Exploitability eXchange

5 Transparency Exchange API - Discovery

5.1 From product identifier to API endpoint

Discovery is the first step in all TEA interactions, enabling a consumer to map an identifier to a service endpoint.

This Standard defines:

  • how discovery is initiated;
  • how discovery documents are retrieved;
  • how API endpoints are obtained.

TEA separates:

  • identity → TEI
  • location → discovery
  • data retrieval → API

Discovery answers the question:

“Where can I retrieve authoritative TEA data for this identifier?”

TEA Discovery is the connection between a product release identifier and the API endpoint. A "product release" is something that the user aquires or downloads - hardware and/or software.

It can be a bundle of many digital devices or software applications. A "product release" normally also has an entry in a large corporation's asset inventory system.

A product release identifier is embedded in a URL where the identifier is one of many existing identifiers or a random string - like an EAN or UPC bar code, UUID, product number or PURL.

The goal is for a user to add this URL to the transparency platform (sometimes with credentials for the selected TEA service, such as an API key) and have the platform access the required artefacts in a highly automated fashion. Those credentials are provisioned separately and are not embedded in the TEI.

5.2 Advertising the TEI

The TEI for a product release can be communicated to the user in many ways.

  • A QR code on a box
  • On the invoice or delivery note
  • For software with a GUI, in an "about" box

The user obtains the TEI from the vendor, through a reseller, or directly. The TEI is defined by the vendor and cannot normally be derived from known information.

5.3 TEA Discovery - defining an extensible identifier

TEA discovery is the process where a user with a product release identifier can discover and download artefacts automatically, with or without authentication. A globally unique identifier is required for a given product release. This identifier is called the Transparency Exchange Identifier (TEI).

"Vendor" means the party that publishes TEIs for its product releases, whether a commercial company or an open source project.

The TEI is based on DNS. The domain name provides a namespace in which the vendor defines product release identifiers using existing or new identifier schemes, such as EAN/UPC bar codes or PURLs. A given product release may have multiple identifiers as long as they all resolve into the same destination. Some identifier schemes require registration with the corresponding standards organisation.

There is no registry of TEIs; only TEI types are registered.

5.4 The TEI: URL - An extensible identifier

The TEI, Transparency Exchange Identifier, is a URL schema that is extensible based on existing identifiers like EAN codes, PURL and other identifiers. It is based on a DNS name, which leads to global uniqueness without new registries.

The TEI can be shown in the software itself, in shipping documentation, in web pages and app stores.

A product release can have multiple TEIs — for example one with an EAN/UPC barcode and one with the vendor's product number.

5.4.1 TEI syntax

A TEI is a URI as defined in RFC 3986, of the form:

tei://<domain-name>/<type>/<unique-identifier>
  • The scheme is tei.
  • The domain-name is a DNS name under the vendor's control. It is the namespace of the TEI and resolves to a web server, which may not be the API host. A port number is not allowed.
  • The type consists of lowercase ASCII letters and digits and starts with a letter. It names the identifier scheme of the unique-identifier and is registered as described in the next section.
  • The unique-identifier is a single path segment in the syntax its type defines and identifies one or more product releases within the domain-name. It shall not contain /, neither literally nor percent-encoded as %2F. Other characters that are not allowed in a path segment are percent-encoded with uppercase hexadecimal digits.

A TEI may identify several product releases, for example when a boxed product keeps its EAN across firmware versions. A successful /discovery response is always a non-empty JSON array, including when it contains only one result. Clients shall treat the array order as priority (first entry highest). See Discovery response. A vendor should make each TEI identify a single product release; a type such as uuid or hash always allows this.

5.4.2 TEI types

TEI types are defined in the TEI type registry at https://github.com/CycloneDX/transparency-exchange-api/tree/main/tei-types. Registration refers to the TEA community process for adding a type, described in the registry.

The following table is informative. It illustrates the types registered at the time of writing; the registry is the authoritative list.

Table 2
Type Unique identifier Example
purl Package URL, Base64URL-encoded without padding tei://example.com/purl/cGtnOm1hdmVuL2NvbW1vbnMtaW8vY29tbW9ucy1pb0AyLjIyLjA
hash Hash of an object, <hashtype>:<hex> tei://example.com/hash/SHA-256:fd44efd601f651c8865acf0dfeacb0df19a2b50ec69ead0262096fd2f67197b9
uuid UUID tei://example.com/uuid/d4d9f54a-abcf-11ee-ac79-1a52914d44b1
eanupc EAN or UPC number tei://example.com/eanupc/1234567890128
gtin GTIN tei://example.com/gtin/0234567890129
asin Amazon Standard Identification Number tei://example.com/asin/B07FZ8S74R
udi Unique Device Identifier tei://example.com/udi/00123456789012

5.4.3 Comparing TEIs

For comparison, a TEI is an opaque identifier, not a locator. Two TEIs are equal if and only if they are the same sequence of characters. The comparison is case-sensitive and applies to the TEI as written:

  • percent-escapes are neither added nor removed,
  • Base64URL-encoded identifiers are not decoded,
  • and the domain name is neither resolved nor normalized.

The following TEIs are therefore all distinct:

tei://example.com/uuid/62f2cf92-ae88-11f1-a698-1a52914d44b2
tei://Example.com/uuid/62f2cf92-ae88-11f1-a698-1a52914d44b2
tei://example.com/uuid/62F2CF92-AE88-11F1-A698-1A52914D44B2
tei://example.com/purl/cGtnOnB5cGkvY3ljbG9uZWR4LXB5dGhvbi1saWI
tei://example.com/purl/cGtnOnB5cGkvY3ljbG9uZWR4LXB5dGhvbi1saWI=

So that one identifier has one spelling, a vendor shall publish a TEI in the following form:

  • the scheme tei in lowercase,
  • the domain name in lowercase ASCII, using A-labels for internationalised names,
  • the type in lowercase,
  • the unique identifier exactly as its registry entry defines it (for example lowercase for a UUID, lowercase hexadecimal for a hash, unpadded Base64URL for a PURL),
  • and no percent-escaping of characters that do not require it.

A client shall use a TEI exactly as received and shall not rewrite it.

When a TEI is carried inside another URL, for example as the tei query parameter of the discovery endpoint, it is percent-encoded for transport. The comparison applies to the TEI after that transport encoding is removed, and a server matching a received TEI against the TEIs it publishes applies this rule.

This rule defines identity only. Resolving a TEI to an API endpoint follows the rules below, where the domain name is used as a DNS name and is therefore case-insensitive.

5.4.4 TEI resolution using DNS

The domain-name part of the TEI is used in a DNS query to find one or multiple locations for product transparency exchange information.

At the URL a well-known name space is used to find out where the API endpoint is hosted. This is solved by using the ".well-known" name space as defined by the IETF.

  • tei://<domain-name>/uuid/62f2cf92-ae88-11f1-a698-1a52914d44b2
  • Syntax: tei://<domain-name>/uuid/<unique identifier>

The name in the DNS name part points to a set of DNS records.

A TEI with domain-name tea.example.com queries DNS for tea.example.com, considering A, AAAA and CNAME records. These point to the hosts available for the Transparency Exchange API.

The TEA client connects to the host using HTTPS and shall verify the server certificate, including the server identity check of RFC 9525. The URL is composed of the host name with the /.well-known/tea path added. The "tea" well-known URI is registred with IANA.

This results in the base URL such as https://products.example.com/.well-known/tea

5.4.5 TEA Discovery document

This response shall contain a JSON object that lists the available TEA server endpoints and supported versions. The JSON shall conform to the TEA Well-Known Schema.

Example:

{
  "schemaVersion": 1,
  "endpoints": [
    {
      "url": "https://api.example.com",
      "versions": 
        [
          "1.0.0"
        ],
      "priority": 1
    },
    {
      "url": "https://api2.example.com/mytea",
      "versions": 
        [
          "1.0.0"
        ],
      "priority": 0.5
    }
  ]
}

5.4.6 Discovery data caching and freshness

Discovery documents may be cached.

Implementations should:

  • respect HTTP caching headers
  • periodically refresh discovery data
  • handle endpoint changes gracefully

5.5 Port resolution

Currently, the port number is not part of the TEI but it is needed to connect to the API.

The TEA API server may be hosted on any port, but the server that is part of the first step of discovery will by default be running on the default HTTPS port 443. In the JSON file found there, the server URLs may contain port numbers.

If the clients are known to support HTTPS/SVCB DNS records for failover and load balancing, these may be used to redirect to other ports and servers.

Public servers are recommended to have the server hosting the DNS name used in the TEI URI running on the default port to enable discovery of the API servers.

5.6 Connecting to the API

Discovery proceeds in two stages that share the same retry, backoff, and attempt-bound rules below:

  1. Well-known stage — retrieve and use /.well-known/tea for the TEI’s domain host
  2. API discovery stage — call /discovery on a selected API base URL constructed from a well-known endpoint entry

5.6.1 Selecting an API base from .well-known/tea

Clients shall pick an endpoint from the .well-known/tea JSON response that lists at least one API version supported by the client. The client shall prefer endpoints whose highest mutually supported version is greatest, based on SemVer 2.0.0 specification comparison rules. Advertised API versions are full SemVer 2.0.0 (MAJOR.MINOR.PATCH with optional prerelease and build metadata). Build metadata is ignored when comparing versions (SemVer 2.0.0 §10), both for precedence and for determining whether the client supports a version. If the highest mutually supported version is advertised with more than one build-metadata spelling, the client may select any of them, and shall use the selected string exactly as advertised when constructing the path (for example /v1.0.0+build.5; + is a valid path character per [RFC3986] and shall not be percent-encoded). If several endpoints remain after that preference, the client should pick the endpoint with the highest priority value (a float between 0 and 1). If priority is absent on a well-known endpoint object, the client shall treat it as 1 for ordering (JSON Schema default does not populate omitted fields in the JSON response).

The client shall then construct the full URL to the API by selecting that highest mutually supported version and appending /v followed by that exact advertised version string (for example /v1.0.0), then /discovery?tei= plus the TEI, url-encoded according to [RFC3986].

Examples:

  1. For TEI tei://products.example.com/uuid/d4d9f54a-abcf-11ee-ac79-1a52914d44b1 https://api.example.com/v1.0.0/discovery?tei=tei%3A//products.example.com/uuid/d4d9f54a-abcf-11ee-ac79-1a52914d44b1
  2. For TEI tei://products.example.com/purl/cGtnOmRlYi9kZWJpYW4vY3VybEA3LjUwLjMtMT9hcmNoPWkzODYmZGlzdHJvPWplc3NpZQ https://api2.example.com/mytea/v1.0.0/discovery?tei=tei%3A//products.example.com/purl/cGtnOmRlYi9kZWJpYW4vY3VybEA3LjUwLjMtMT9hcmNoPWkzODYmZGlzdHJvPWplc3NpZQ

The discovery endpoint is a part of the TEA OpenAPI specification. Unlike /token, /discovery is required on a conforming TEA API base: a conforming server that exposes a given API version shall implement it.

5.6.2 Discovery response

A successful /discovery response is a non-empty JSON array of discovery-info objects, including when it contains only one result. Each element identifies one resolved product release and the TEA servers that serve it:

  • productReleaseUuid — UUID of the TEA Product Release
  • servers — non-empty array of server-info objects (rootUrl, versions, and optional priority)

.well-known/tea and servers[] are related but distinct:

  • Well-known lists candidate API bases for a domain. That is where the client calls /discovery (after appending /v{version}).
  • servers[] in the discovery response lists API bases that serve the resolved product release. The client selects among them with the same version-preference and priority rules as for well-known endpoints. A rootUrl need not appear in the well-known endpoint list. All further requests for that product release are built as rootUrl + /v + the selected version + path. The API base used for /discovery is not used again for that release unless it is also listed in servers[].

When multiple product releases match, the array is ordered by priority (first entry highest). Vendors should prefer returning a single release when possible.

A successful lookup shall return a non-empty array. If the server does not resolve the identifier, the server shall respond with 404 and a TEA error body with error: OBJECT_UNKNOWN — not 200 with an empty array. If priority is absent on a discovery servers[] entry, the client shall treat it as 1 for ordering, the same as for well-known endpoints.

Example (one match):

[
  {
    "productReleaseUuid": "d4d9f54a-abcf-11ee-ac79-1a52914d44b1",
    "servers": [
      {
        "rootUrl": "https://api.example.com",
        "versions": ["1.0.0"]
      }
    ]
  }
]

5.6.3 Discovery by PURL

Clients that already know a TEA API base URL (for example from a prior TEI discovery, configuration, or cache) may call /discovery with the purl query parameter instead of tei. Exactly one of tei or purl shall be provided; a request with neither or both is rejected with 400.

Discovery by PURL resolves within the inventory of the TEA server that receives the request. It does not replace TEI-based DNS / .well-known discovery for finding an API host from an identifier alone.

Example:

https://api.example.com/v1.0.0/discovery?purl=pkg%3Amaven%2Forg.apache.logging.log4j%2Flog4j-core%402.24.3

The response shape, non-empty success array, and 404 with OBJECT_UNKNOWN when the server does not resolve the identifier are the same as for TEI lookup.

5.6.4 Unresolved identifiers

If the server does not resolve the requested TEI or PURL, either because the identifier is unknown or because the server withholds the resolution result, the /discovery endpoint shall return 404 with a TEA error response (see the 404-object-by-id-not-found response).

A response is a TEA error response only when its Content-Type is application/json (optionally with parameters such as charset) and its body is a JSON object with a string error property, typically OBJECT_UNKNOWN. Clients shall ignore properties they do not recognize and shall not reject the response for an error value they do not know, so that a later TEA version can extend error-response without turning its 404 responses into failover triggers. Other JSON 404 bodies, such as {"message":"Not Found"}, are not TEA error responses.

On a 404 TEA error response from /discovery, the client:

  • shall not infer from the status alone whether the identifier is unknown or the resolution result is withheld;
  • shall not treat the response as meaning that /discovery is missing, and shall not fail over to another endpoint solely because of the response;
  • shall stop discovery for that identifier at this authority and report that the identifier could not be resolved there, including the error value received; and
  • shall not report that outcome as evidence that no updates are available.

A 404 that is not a TEA error response is a failed attempt; see Failover, invalid documents, and attempt bounds.

5.6.5 Failover, invalid documents, and attempt bounds

The following failure classes count as a failed attempt for the current candidate and are subject to the same total attempt bound, backoff, and TLS verification rules, whether they occur in the well-known stage or the API discovery stage:

  • DNS resolution failure for the host being contacted
  • TLS certificate validation failure
  • HTTP 5xx from the host being contacted
  • A 404 that is not a TEA error response as defined in Unresolved identifiers (for example a web server answering for an unmounted path, or a JSON body without an error property)
  • A response body that is not usable JSON, or that does not conform to the expected schema for that stage (malformed or non-conforming .well-known/tea, or an invalid /discovery success body)

A conforming TEA /discovery 404 (error-response, typically OBJECT_UNKNOWN) is not a failover trigger; see Unresolved identifiers.

On such a failure, the client shall select the next untried well-known endpoint that supports a compatible API version, if one is available. While doing so the client should preserve priority order from highest to lowest (applying the absent-priority equals 1 rule). Each failover connection is subject to the same TLS verification requirement. Clients should limit the total number of attempts across both stages for a discovery operation. Additional attempts should use exponential backoff. When a retry limit is reached, the client shall report that discovery could not be completed, indicating which stage failed when that is known.

5.6.6 Authentication and authorization

Where authentication is required, clients use credentials configured for the selected TEA service, such as an API key, to obtain a TEA access token from that service’s /token endpoint. Credentials shall not be embedded in a TEI. API keys are exchanged only at the selected API’s /token endpoint; clients shall not probe /token to discover whether authentication is required.

A protected TEA resource endpoint (excluding /token) shall respond to a request without valid authentication with 401 Unauthorized and a WWW-Authenticate: Bearer challenge. When that challenge contains error="invalid_token" (RFC 6750 section 3.1), the client may obtain a replacement access token from the same service and retry the original request once. Clients should not repeat this recovery attempt for the same request. This is not OAuth refresh-token use.

A TEA server that requires no authentication on any endpoint need not implement the /token endpoint, shall not answer any resource request with 401, and shall ignore, rather than reject, an Authorization: Bearer header a client presents anyway.

If authentication cannot be completed or recovery fails, the client shall indicate that update status could not be determined. Failures that may require user or administrator intervention include rejected or revoked credentials, expired client certificates, persistent rejection of a replacement token, and insufficient permissions. A 403 Forbidden response indicates denied authorization and shall not trigger token-replacement attempts solely because of that status. Clients shall not fail over to another endpoint solely in response to 401 or 403.

Clients shall verify server certificates for every HTTPS connection used in discovery and subsequent API access, including the server identity check of RFC 9525, and shall not use connections that fail validation.

Clients shall not automatically forward a TEA access token to a different origin, or outside the authorized API base URL of the service that issued it. API-key Basic credentials shall not be forwarded based merely on a discovery redirect; a different service requires independently configured credentials. Redirect targets used during discovery or API access shall use HTTPS and are subject to the same certificate verification requirement.

The full client authentication flow is described in Authentication. The rules above align discovery with that model and do not replace it.

How authentication or authorization failures are presented to end users is implementation specific, but they shall not be reported as evidence that no updates are available.

5.6.7 Common authentication-related responses

5.6.7.1 401 Unauthorized

  • For an initially unauthenticated resource request, a WWW-Authenticate: Bearer challenge without an error parameter indicates that authentication is required. A client with configured credentials may obtain an access token from the selected API’s /token endpoint and retry the resource request.
  • For a resource request rejected with error="invalid_token", the client may obtain a replacement access token from the same service and retry the original request once. Clients should not repeat this recovery attempt for the same request.

Other challenges shall not be interpreted as instructions to repeatedly obtain replacement tokens.

5.6.7.2 403 Forbidden

  • Authenticated, but not authorized for this resource. Do not treat as token expiry and do not fail over solely because of this status.

Common errors:

5.6.7.3 404 Not Found

  • On /discovery, a TEA error response (application/json body with a string error property, typically OBJECT_UNKNOWN): this server does not resolve the TEI or PURL, whether unknown or withheld. Do not fail over. Stop and report that the identifier could not be resolved at this authority, with the error value; do not report that as evidence that no updates are available.
  • A 404 that is not a TEA error response may mean the path is not mounted or the host is not a TEA API base; treat that as a failed discovery attempt and failover if another compatible endpoint remains. This is distinct from /token, where 404 means only that the token endpoint is not implemented.

5.6.7.4 503 Service Unavailable

  • temporary failure

5.6.7.5 TLS failure

  • certificate validation error

5.6.8 Client behavior

Clients should:

  • retry with backoff
  • validate TLS certificates
  • fail closed if discovery cannot be validated

5.7 Notes Regarding .well-known

Servers shall not locate the actual TEA service endpoint at the /.well-known/tea URI. This URI is reserved for the TEA discovery document and uses the well-known URI mechanism defined in RFC 8615.

5.7.1 TLS Encryption

Note

HTTP is the protocol. http and https are URI schemes, the part of a URL before the colon, as in https://. The https scheme identifies HTTP over TLS, which this document calls HTTPS.

The .well-known endpoint shall only be available via HTTPS. The client shall verify the server certificate for that connection against the TEI domain-name, using the server identity check of RFC 9525, so that the host is the one named in the TEI.

Example of resolving a TEI to the well-known URL:

  • TEI: tei://products.example.com/uuid/d4d9f54a-abcf-11ee-ac79-1a52914d44b1
  • URL: https://products.example.com/.well-known/tea

Conforming deployments shall advertise only lowercase https base URLs, in .well-known/tea endpoints[].url and in /discovery servers[].rootUrl alike. A client shall reject an http base URL unless it has been explicitly configured to allow that specific base for local testing. The allowance is per configured base URL, never a global setting, so it cannot apply to a base the client learned from discovery. Credentials may be sent to a base allowed this way; a deployment that relies on it is not conforming.

5.8 References

Normative Optional

6 Authentication and authorization

This document covers authentication and authorization on the consumer side of a TEA service - the discovery and download of software transparency artefacts.

A user of a TEA service may get access to all objects (components, collections) and artefacts or just a subset, depending on the publisher of the data. Authorization is connected to authentication.

The level of authorization is up to the implementer of the TEA implementation and the publisher, whether an identity gets access to all objects in a service or just a subset.

In order to get interoperability between clients and servers implementing the protocol, the specification focuses on the authentication. After successful authentication, the authorization may be implemented in multiple ways - on various levels of the API - depending on what information the user can access.

As an example, one implementation may publish all information about existing artefacts and software versions openly, but restrict access to artefacts to those that match the user's installation. Another implementation can implement a filter that does not show products and versions ("components") that the user has not acquired.

For most Open Source projects, implementing authentication - setting up accounts and managing authorization - does not make much sense, since the information is usually in the open anyway.

6.1 Authentication is not required in this standard

This specification does not require a TEA server to authenticate its users.

The requirements of this chapter apply to a TEA server that requires authentication for some or all of its objects, and therefore implements the token endpoint, and to a TEA client that accesses such a server. Such a server implements the baseline below in full; see Servers that protect some objects.

A TEA server that requires no authentication need not implement anything in this chapter, including the token endpoint. The rules such a server follows are in the "Authentication and authorization" section of Discovery; see also Servers without authentication.

6.2 Authentication baseline

Where a service does authenticate, interoperability requires that every TEA client can authenticate against every TEA server without server-specific code. This specification therefore defines a single mandatory baseline and leaves everything above it optional:

  • A TEA server that requires authentication shall implement the token endpoint (POST /token) described below, and shall support the API key credential exchange on it.
  • A TEA server may support additional credential types on the same endpoint - federated identity from an external OpenID Connect or SAML provider, mutual TLS, or others.
  • A client that holds an API key for a TEA service shall be able to reach every endpoint it is authorized for using only the baseline exchange.

Two consequences are worth stating explicitly, because they are what make the baseline useful:

  • All authenticated access goes through the token endpoint. A server shall not accept an API key directly on the resource endpoints, and a client shall not present one there. The API key is exchanged for an access token, and the access token is what the resource endpoints see.
  • Whatever credential a client starts with, it ends up holding the same thing: a TEA access token presented as an HTTP bearer token. Clients therefore need one code path for the API itself, regardless of how the server manages identity.

6.2.1 The token endpoint

The token endpoint is POST /token, relative to the TEA API base URL, and is defined in the TEA OpenAPI specification alongside the resource endpoints. It is an OAuth 2.0 token endpoint as defined in RFC 6749 section 3.2; this specification constrains which grant types a conforming server shall accept, and adds nothing to the wire format.

RFC 6749 leaves the location of the token endpoint outside its scope - /token appears only in its examples - so TEA fixes the path here rather than requiring clients to discover it. TEA defines no OAuth 2.0 authorization endpoint (RFC 6749 section 3.1): there is no interactive, browser-based consent step in TEA, and every grant type described below is one a client can complete on its own.

6.2.2 API key exchange (mandatory)

An API key consists of two parts issued together by the service: an identifier and a secret. The identifier need not be confidential; the secret is.

The client presents them using the HTTP Basic authentication scheme (RFC 7617) - the identifier as the user-id and the secret as the password - with the client_credentials grant type. This is OAuth 2.0 client authentication as described in RFC 6749 section 2.3.1, which requires a token endpoint to support Basic for clients that were issued a secret.

POST /token HTTP/1.1
Host: tea.example.com
Authorization: Basic <base64 of "key-id:key-secret">
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Per RFC 6749 section 2.3.1 the identifier and secret are each application/x-www-form-urlencoded encoded before being joined with a colon and Base64 encoded. This only matters when a credential contains a colon or characters outside US-ASCII, but clients and servers shall apply it so that such credentials interoperate.

Servers may additionally accept the credentials as client_id and client_secret form parameters in the request body. RFC 6749 section 2.3.1 marks this as NOT RECOMMENDED and limits it to clients that cannot use Basic, so clients should use Basic where they can.

A successful response is the standard OAuth 2.0 token response (RFC 6749 section 5.1):

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 3600
}

Errors are the standard OAuth 2.0 token error response (RFC 6749 section 5.2), for example invalid_client for a bad API key or unsupported_grant_type for a grant the server does not implement.

6.2.3 Using the access token

The access token is presented on every other TEA endpoint as an HTTP bearer token (RFC 6750):

GET /product/d4d9f54a-abcf-11ee-ac79-1a52914d44b1 HTTP/1.1
Host: tea.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

The access token is opaque to the client. Clients shall not inspect, parse, or depend on the contents of the token, and shall not assume any particular format. Servers are free to issue a random handle, a signed token such as a JWT access token (RFC 9068), or anything else, and to change that choice without notice; only the issuing server interprets it.

Token lifetime, storage, rotation, and revocation are implementation matters and are deliberately not specified. Two rules keep clients simple in spite of that:

  • Servers should return expires_in, so that a client can obtain a new token before the current one expires rather than discovering expiry through a failed request.

  • If a request to a resource endpoint fails with 401 and the WWW-Authenticate challenge header carries error="invalid_token", the client may obtain a new token from the token endpoint and retry the request once, as described in RFC 6750 section 3.1. A client should not retry more than once for a single request. The error code is an attribute of the challenge header; it is not carried in the token, which remains opaque:

    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: Bearer realm="tea", error="invalid_token", error_description="The access token expired"
    

Between them these cover server-side revocation without the client having to know it happened: RFC 6750 defines invalid_token as covering tokens that are "expired, revoked, malformed, or invalid for other reasons". This specification defines no revocation endpoint, and clients need not implement one.

No refresh tokens. Servers should not issue refresh tokens with the client_credentials grant, following RFC 6749 section 4.4.3. A refresh token exists so that a client can obtain a new access token without re-presenting a credential, which matters when the credential belongs to a user who is no longer present. A TEA client holds its own API key permanently and can simply call the token endpoint again, so a refresh token would be a second long-lived secret to store and protect for no benefit.

6.3 Optional credential types

A server may accept credentials other than an API key at the same token endpoint, selected by the grant_type parameter. In every case the response is the same token response, and the resulting access token is used the same way, so clients that already implement the baseline need only the additional request.

The following are the cases we expect to be common. All are existing OAuth 2.0 profiles; TEA adds nothing to them.

Table 3: OAuth 2.0 grant types for optional credentials
Use case Grant type Specification
Enterprise SSO where the user's identity provider issues SAML assertions urn:ietf:params:oauth:grant-type:saml2-bearer RFC 7522
OpenID Connect, or any provider issuing signed JWTs, including workload identity in CI systems urn:ietf:params:oauth:grant-type:jwt-bearer RFC 7523
A client already holding a token from another security domain, exchanged for a TEA token urn:ietf:params:oauth:grant-type:token-exchange RFC 8693
A client authenticated by a TLS client certificate rather than a shared secret client_credentials with mutual TLS client authentication RFC 8705

RFC 8693 token exchange (urn:ietf:params:oauth:grant-type:token-exchange) is outside the scope of the TEA 1.0 interoperable authentication profile. TEA 1.0 does not specify the request or response contract for this grant. Implementations may support it as an extension by separate agreement, but clients shall not assume its availability based solely on TEA 1.0 conformance. Such extensions do not remove the requirement for servers requiring authentication to support the client_credentials baseline.

RFC 7521 defines the common framework the two assertion grants share.

Note that a server which delegates identity to an external provider still issues its own TEA access token from its own token endpoint. The external provider authenticates the user; the TEA server decides what that user may see. This keeps authorization with the party that owns the data, and keeps the resource endpoints validating exactly one kind of token.

6.3.1 Mutual TLS

Mutual TLS is a client authentication method at the token endpoint, not a separate way in. A client authenticated by a certificate presents no Authorization header on its token request; the certificate identifies it. RFC 8705 additionally allows the issued access token to be bound to the certificate, so that a stolen token is useless without the corresponding private key.

Client certificates are managed by the service and provided in a service-specific way. Clients should be able to configure a separate client certificate and private key per TEA service, and should not assume that a client certificate for one service is trusted anywhere else.

6.4 Transport security

All of the above assumes TLS. Credentials and bearer tokens are transmitted in the clear at the HTTP layer, so a TEA server shall be reachable only over TLS, and clients shall verify the server certificate, including the server identity check of RFC 9525. This restates RFC 6749 section 3.2 and RFC 6750 section 5.

6.5 Client flow

Whether a server requires authentication is discovered by using it, not by configuration and not by probing the token endpoint. In TEA, resource operations may be called with a Bearer token or without one; a 401 with a WWW-Authenticate: Bearer challenge on a given endpoint is the runtime signal that a token is required there. The complete flow for a client that does not know in advance:

  1. The client sends the resource request it wants, with no credentials.
  2. If the server does not require authentication for that endpoint, it answers 200 with the resource. The client is done.
  3. If the server requires authentication, it answers 401 with a WWW-Authenticate header naming the Bearer scheme, as described in RFC 6750 section 3. This challenge is the only signal a client needs.
  4. The client calls POST /token with its credential - for the baseline, the API key over HTTP Basic - and receives an access token. Unauthenticated client_credentials requests shall not be accepted; an empty OpenAPI security requirement on /token allows alternate client authentication (for example, mutual TLS, JWT client assertion (RFC 7523), or credentials in the request body), not anonymous token issuance.
  5. The client repeats the resource request with Authorization: Bearer <access_token>, and presents the same token on subsequent requests until it expires or is rejected.
  6. When a later request fails with 401 and error="invalid_token", the client obtains a fresh token and retries that request once, as described above.

A client that already holds an API key for a service may skip steps 1 to 3 and call the token endpoint first: being issued a key is itself the signal that the service requires authentication. Trying the resource first is for the case where the client does not know.

Two things the flow deliberately avoids. A client shall not probe /token to find out whether authentication exists; the challenge on the resource is the discovery mechanism, and a 404 from /token means only that the endpoint is not implemented. And a client shall not send its API key to a resource endpoint; the key goes to the token endpoint only, and resource endpoints see bearer tokens only.

The cost of the unknown case is one wasted request per server, once. This is the standard HTTP pattern and is preferred over any configuration or discovery step a client would otherwise need.

6.5.1 Servers without authentication

A server that requires no authentication on any endpoint (and therefore applies no authorization) follows the rules in the "Authentication and authorization" section of Discovery: it need not implement the token endpoint, it does not answer resource requests with 401, and it ignores an Authorization: Bearer header a client presents anyway.

There is nothing to exchange on such a server: an OAuth 2.0 token response carries an access token, and the mandatory grant requires the client to authenticate, so a token endpoint could only issue a token that means nothing. Its clients complete step 2 of the flow above and never look for the token endpoint. A client that presents a token anyway, for example one obtained elsewhere or applied by habit, keeps working, because the token is ignored.

6.5.2 Servers that protect some objects

A TEA server may make some data available without authentication while requiring authentication and authorization for other objects - for example, listing products and releases without a token while restricting artifact downloads to some users. Such a server requires authentication for the protected objects:

  • it shall implement the token endpoint and the baseline exchange, because at least one object needs them;
  • endpoints that do not require authentication answer without a token and ignore a token that is presented;
  • protected endpoints shall answer 401 with the Bearer challenge when no valid token is presented, which is how a client learns, per endpoint, that a token is needed. They shall not answer a concealing 404 solely because the client is unauthenticated. A client should not assume that a server which served one object without authentication will serve every object without authentication, nor the reverse.

Authorization - which of the protected data an authenticated client may see - is the server's decision and is not constrained by this specification; a client with a valid token may still receive a filtered view, 403 Forbidden, or a concealing 404 Not Found for individual objects it is not authorized to see. Clients shall not infer from 404 alone whether the object is absent or withheld.

6.5.3 Protected resource metadata

Servers that delegate identity to an external provider may publish OAuth 2.0 protected resource metadata (RFC 9728) and reference it from the WWW-Authenticate challenge, allowing a client to locate the authorization server automatically. This is optional; it does not replace the token endpoint, which remains the interoperable baseline, and it does not replace the challenge as the way a client discovers that authentication is required.

6.6 References

6.6.1 A note on API keys and X-API-Key

There is no IETF specification for API keys, and no registered HTTP authentication scheme for them. A survey of the IETF datatracker finds only working-group discussion material and an early individual draft, nothing normative. The widespread X-API-Key header is additionally at odds with RFC 6648, a Best Current Practice that deprecates the X- prefix for new header fields.

This specification therefore carries the API key in the standard Authorization header using the Basic scheme, which is registered, specified, supported directly by essentially every HTTP client library, and already the mandatory-to-implement client authentication method for OAuth 2.0 token endpoints. The result is no harder for a client than a custom header - it is one line in any HTTP library - and it avoids inventing a TEA-specific credential format.

7 UUID Scope and Stability

This document defines the scope of uniqueness and the stability guarantees of UUIDs used by TEA objects (TEA Product, TEA Product Release, TEA Component, TEA Component Release, TEA Collection, TEA Artifact).

7.1 Uniqueness scope

Paths such as /productRelease/{uuid} name an object by the API base and the UUID. The request does not carry the TEI authoritative domain, so two different objects that share a UUID at the same API base cannot be distinguished.

A TEA UUID alone is not globally unique. Uniqueness for retrieval is the tuple:

API base + object type + UUID
  • The API base is the base URL of the TEA API the client calls. For each object type, a TEA server shall ensure that a UUID refers to at most one object served at that API base.
  • The authoritative domain is supplied by the TEI (tei://<domain-name>/<type>/<unique-identifier>); see discovery. It tells a client which API to call. It is not part of a UUID path. TEA has no centralized authority that assigns UUIDs, so uniqueness across different API bases is not enforced by the protocol.
  • The object type scopes uniqueness to a single object class (Product, Product Release, Component, Component Release, Collection, Artifact). Except as noted below, UUIDs are not required to be unique across object types.

If two authoritative domains would assign the same UUID to different objects of the same type, those domains shall be served from different API bases. One API base shall not host both.

Exception: Product Release and Component Release. A TEA Collection shall use the same UUID as its parent Product Release or Component Release. Within an API base, a Product Release and a Component Release shall not share a UUID. Consequently, Collections belonging to different parent releases have different UUIDs. Versions of the same Collection retain the same UUID. Except for Product Release and Component Release, objects of different types may share a UUID.

The per-object-type scoping reflects how TEA servers are typically implemented: each object type lives in its own database table, where uniqueness is trivially enforced by a primary key. Cross-table uniqueness is not required in general (TEA has no operation that resolves a UUID without already knowing its object type), except that Product Release and Component Release UUIDs shall be disjoint as above, because those types share the Collection UUID namespace.

Implementations may use any UUID version defined in RFC 9562. Implementations should create UUIDs with a cryptographically secure random number generator: UUID version 4, or version 7 whose random bits are drawn that way. Independently created UUIDs are then unique across TEA servers for practical purposes. This does not replace the rule above. A server shall not assign a UUID that is already in use at its API base for that object type, including a UUID already used for the other release type.

7.2 Stability

All TEA UUIDs shall be stable for the lifetime of the resource they identify, within a given TEA server. Specifically:

  • A UUID shall not be reassigned to a different resource.
  • A UUID shall not change across backup/restore or re-hosting of the same TEA service instance.

Stability is required for all TEA object types, not only TEA Product Release. While TEI resolution targets only Product Release UUIDs, clients routinely bookmark and cache sub-resource URLs (e.g. /component/{uuid}, /componentRelease/{uuid}, /productRelease/{uuid}); changing those UUIDs would silently break those clients.

8 The TEA API

The Transparency Exchange API (TEA) aims to facilitate the automated exchange of supply chain artifacts such as Software Bill of Materials (SBOM), Vulnerability Exploitability eXchange (VEX), and attestations, allowing users to automatically discover and consume transparency-related artifacts for a product. The TEA enhances transparency across the software supply chain by providing a standardized method to share and access critical security and compliance information. This automation benefits release management and optimizes procurement processes, ensuring timely updates and improving risk management. TEA is developed within the OWASP CycloneDX project and standardised in ECMA International technical Committee 54, task group 1.

8.1 Security

Table 4: Security schemes
Scheme Type Description
bearerAuth http bearer

A TEA access token obtained from /token, presented as Authorization: Bearer <access_token> (RFC 6750). This is the only credential accepted on TEA endpoints other than /token.

Resource operations declare both this requirement and an empty alternative so that a server can select which objects require authentication: a client may call without a token. Whether a given endpoint actually requires a token is discovered at runtime from a 401 Bearer challenge (see 401-unauthorized), not from this document alone. A server that requires no authentication shall ignore a presented Bearer token. A server that protects some objects but not all may leave some endpoints without authentication and protect others. Authorization after authentication (filtered views, 403, or a concealing 404 for an authenticated but unauthorized client) remains server-specific. A protected object with no valid token shall answer 401, not a concealing 404.

basicAuth http basic API key credentials, presented to /token only: the API key identifier as the user-id and the API key secret as the password (RFC 7617, RFC 6749 section 2.3.1). Per RFC 6749 section 2.3.1, the identifier and secret are each encoded as application/x-www-form-urlencoded before they are joined with a colon and Base64-encoded for the Authorization header. Clients and servers shall apply that encoding so credentials containing :, @, or other reserved characters interoperate. Servers shall not accept API key credentials directly on other TEA endpoints; clients shall exchange them for an access token first.

Unless an operation states otherwise, every operation requires: bearerAuth or none (anonymous access).

8.2 TEA Discovery

8.2.1 Resolve an identifier to TEA Product Releases

GET/discovery

Discovery endpoint which resolves an identifier into one or more product release UUIDs.

Exactly one of the tei and purl query parameters shall be provided. A request with neither, or with both, is rejected with 400. OpenAPI cannot express this constraint on query parameters, so both are declared optional here.

Discovery by TEI resolves the product across TEA servers, using the domain carried by the TEI (typically after DNS / .well-known selection of an API host). Discovery by PURL requires an already-known API base URL and resolves within that server's inventory.

A successful response is a non-empty JSON array of discovery-info objects, ordered by priority when multiple product releases match (first entry highest). If the server does not resolve the identifier, it responds with 404 and error: OBJECT_UNKNOWN, not 200 with an empty array.

Parameter values are the identifier itself (not a pre-encoded wire form). Clients shall apply query-parameter serialization once. Servers shall interpret the value after one query-decoding step. Escapes that are part of a PURL value are preserved by that single decode.

Example request lines after serialization:

  • .../discovery?tei=tei%3A%2F%2Fproducts.example.com%2Fuuid%2F47f51950-b0e2-11f1-adc2-1a52914d44b2
  • .../discovery?purl=pkg%3Amaven%2Forg.apache.logging.log4j%2Flog4j-core%402.24.3

Unlike /token, this operation is required on a conforming TEA API base for the advertised version. A conforming 404 uses the shared object-not-found response (error-response, typically OBJECT_UNKNOWN) and means this server does not resolve the identifier, not that /discovery is optional or unimplemented. Client recognition of that body and the terminal outcome are defined in the discovery document.

Table 5: Parameters
Name In Required Type Description
tei query No string Transparency Exchange Identifier (TEI) for the product being discovered, as the logical TEI string. Do not pre-encode for the schema example or client model; apply query-parameter encoding once when forming the HTTP request.
purl query No string Package URL (PURL) of the product being discovered, resolved within this TEA server's inventory, as the logical PURL string. Do not pre-encode for the schema example or client model; apply query-parameter encoding once when forming the HTTP request.
Table 6: Responses
Status Description Schema
200 Non-empty array of discovery results for the requested TEI or PURL. Each element is a discovery-info object (productReleaseUuid plus servers). An empty array is not a valid success response; use 404 with error: OBJECT_UNKNOWN when the server does not resolve the identifier. Array of discovery-info
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 7: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.3 TEA Product

8.3.1 Query TEA Products

GET/products

Returns a list of TEA products. Note that multiple products may match.

Table 8: Parameters
Name In Required Type Description
idType query No identifier-type Type of identifier specified in the idValue parameter
idValue query No string If present, only the objects with the given identifier value will be returned.
pageSize query No integer The maximum number of results to return.
Default: 25. Minimum: 1. Maximum: 100. Format: int64.
pageToken query No string

An opaque continuation token produced by a previous response. This token shall be copied verbatim from the nextPageToken value returned by the previous response. Clients shall not parse, construct, or modify this token.

The token represents continuation state for the original query, including sortField, sortOrder, result-affecting filters such as idType and idValue, and path parameters such as parent uuid. When pageToken is supplied, clients shall not change those result-affecting query parameters. Servers shall return 400 Bad Request if supplied result-affecting query parameters conflict with the token state. To change any result-affecting parameter, clients shall start a new pagination sequence without pageToken.

A pageToken is only valid with the same request path and same path parameter values used to obtain it. Clients shall not reuse a pageToken across different parent resource paths or different path uuid values. Servers shall return 400 Bad Request when a pageToken is used with a different path or different path parameter values.

Servers shall return 400 Bad Request for malformed, invalid, expired, or conflicting pageToken values.

sortField query No string (enum)

The field by which to sort the results.

Paginated results shall be ordered first by the selected sortField, then by uuid as a deterministic secondary tie-breaker.

One of: name. Default: "name".

sortOrder query No string (enum)

The direction of the sort.

The default is asc for all paginated resources. Clients that need newest release or collection versions first can request sortOrder=desc.

The selected sort order applies to both the primary sortField and the resource-specific deterministic secondary tie-breaker. For products, components, product releases, and component releases, the secondary key is uuid. For collections, the secondary key is version if additional tie-breaking is needed.

One of: asc, desc. Default: "asc".

Table 9: Responses
Status Description Schema
200 A paginated response containing TEA Products paginated-product-response
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
Table 10: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.3.2 Get a TEA Product

GET/product/{uuid}

Get a TEA Product by UUID

Table 11: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of the TEA product in the TEA server
Table 12: Responses
Status Description Schema
200 Requested TEA Product found and returned product
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 13: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.4 TEA Product Release

8.4.1 List the releases of a TEA Product

GET/product/{uuid}/releases

Get releases of the product

Table 14: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Product in the TEA server
pageSize query No integer The maximum number of results to return.
Default: 25. Minimum: 1. Maximum: 100. Format: int64.
pageToken query No string

An opaque continuation token produced by a previous response. This token shall be copied verbatim from the nextPageToken value returned by the previous response. Clients shall not parse, construct, or modify this token.

The token represents continuation state for the original query, including sortField, sortOrder, result-affecting filters such as idType and idValue, and path parameters such as parent uuid. When pageToken is supplied, clients shall not change those result-affecting query parameters. Servers shall return 400 Bad Request if supplied result-affecting query parameters conflict with the token state. To change any result-affecting parameter, clients shall start a new pagination sequence without pageToken.

A pageToken is only valid with the same request path and same path parameter values used to obtain it. Clients shall not reuse a pageToken across different parent resource paths or different path uuid values. Servers shall return 400 Bad Request when a pageToken is used with a different path or different path parameter values.

Servers shall return 400 Bad Request for malformed, invalid, expired, or conflicting pageToken values.

sortField query No string (enum)

The field by which to sort the results.

Paginated results shall be ordered first by the selected sortField, then by uuid as a deterministic secondary tie-breaker.

When version is selected, ordering is by the stored version string according to the server's documented string collation; semantic-version precedence is not implied. Servers shall apply a stable and deterministic string collation for version sorting, and the same collation shall be used consistently across pages for a pagination sequence.

When releaseDate is selected, releases without a releaseDate shall be ordered consistently. Missing releaseDate values sort after populated releaseDate values for ascending order and before populated releaseDate values for descending order.

One of: createdDate, releaseDate, version. Default: "createdDate".

sortOrder query No string (enum)

The direction of the sort.

The default is asc for all paginated resources. Clients that need newest release or collection versions first can request sortOrder=desc.

The selected sort order applies to both the primary sortField and the resource-specific deterministic secondary tie-breaker. For products, components, product releases, and component releases, the secondary key is uuid. For collections, the secondary key is version if additional tie-breaking is needed.

One of: asc, desc. Default: "asc".

Table 15: Responses
Status Description Schema
200 A paginated response containing TEA Product Releases paginated-product-release-response
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 16: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.4.2 Query TEA Product Releases

GET/productReleases

Returns a list of TEA product releases. Note that multiple product releases may match.

Table 17: Parameters
Name In Required Type Description
idType query No identifier-type Type of identifier specified in the idValue parameter
idValue query No string If present, only the objects with the given identifier value will be returned.
pageSize query No integer The maximum number of results to return.
Default: 25. Minimum: 1. Maximum: 100. Format: int64.
pageToken query No string

An opaque continuation token produced by a previous response. This token shall be copied verbatim from the nextPageToken value returned by the previous response. Clients shall not parse, construct, or modify this token.

The token represents continuation state for the original query, including sortField, sortOrder, result-affecting filters such as idType and idValue, and path parameters such as parent uuid. When pageToken is supplied, clients shall not change those result-affecting query parameters. Servers shall return 400 Bad Request if supplied result-affecting query parameters conflict with the token state. To change any result-affecting parameter, clients shall start a new pagination sequence without pageToken.

A pageToken is only valid with the same request path and same path parameter values used to obtain it. Clients shall not reuse a pageToken across different parent resource paths or different path uuid values. Servers shall return 400 Bad Request when a pageToken is used with a different path or different path parameter values.

Servers shall return 400 Bad Request for malformed, invalid, expired, or conflicting pageToken values.

sortField query No string (enum)

The field by which to sort the results.

Paginated results shall be ordered first by the selected sortField, then by uuid as a deterministic secondary tie-breaker.

When version is selected, ordering is by the stored version string according to the server's documented string collation; semantic-version precedence is not implied. Servers shall apply a stable and deterministic string collation for version sorting, and the same collation shall be used consistently across pages for a pagination sequence.

When releaseDate is selected, releases without a releaseDate shall be ordered consistently. Missing releaseDate values sort after populated releaseDate values for ascending order and before populated releaseDate values for descending order.

One of: createdDate, releaseDate, version. Default: "createdDate".

sortOrder query No string (enum)

The direction of the sort.

The default is asc for all paginated resources. Clients that need newest release or collection versions first can request sortOrder=desc.

The selected sort order applies to both the primary sortField and the resource-specific deterministic secondary tie-breaker. For products, components, product releases, and component releases, the secondary key is uuid. For collections, the secondary key is version if additional tie-breaking is needed.

One of: asc, desc. Default: "asc".

Table 18: Responses
Status Description Schema
200 A paginated response containing TEA Product Releases paginated-product-release-response
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
Table 19: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.4.3 Get a TEA Product Release with its latest collection

GET/productRelease/{uuid}

Get the TEA Product Release with its latest collection

Table 20: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Product Release in the TEA server
Table 21: Responses
Status Description Schema
200 Requested TEA Product Release and its latest Collection found and returned product-release-with-collection
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 22: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.5 TEA Component

8.5.1 Query TEA Components

GET/components

Returns a list of TEA components. Note that multiple components may match.

Table 23: Parameters
Name In Required Type Description
idType query No identifier-type Type of identifier specified in the idValue parameter
idValue query No string If present, only the objects with the given identifier value will be returned.
pageSize query No integer The maximum number of results to return.
Default: 25. Minimum: 1. Maximum: 100. Format: int64.
pageToken query No string

An opaque continuation token produced by a previous response. This token shall be copied verbatim from the nextPageToken value returned by the previous response. Clients shall not parse, construct, or modify this token.

The token represents continuation state for the original query, including sortField, sortOrder, result-affecting filters such as idType and idValue, and path parameters such as parent uuid. When pageToken is supplied, clients shall not change those result-affecting query parameters. Servers shall return 400 Bad Request if supplied result-affecting query parameters conflict with the token state. To change any result-affecting parameter, clients shall start a new pagination sequence without pageToken.

A pageToken is only valid with the same request path and same path parameter values used to obtain it. Clients shall not reuse a pageToken across different parent resource paths or different path uuid values. Servers shall return 400 Bad Request when a pageToken is used with a different path or different path parameter values.

Servers shall return 400 Bad Request for malformed, invalid, expired, or conflicting pageToken values.

sortField query No string (enum)

The field by which to sort the results.

Paginated results shall be ordered first by the selected sortField, then by uuid as a deterministic secondary tie-breaker.

One of: name. Default: "name".

sortOrder query No string (enum)

The direction of the sort.

The default is asc for all paginated resources. Clients that need newest release or collection versions first can request sortOrder=desc.

The selected sort order applies to both the primary sortField and the resource-specific deterministic secondary tie-breaker. For products, components, product releases, and component releases, the secondary key is uuid. For collections, the secondary key is version if additional tie-breaking is needed.

One of: asc, desc. Default: "asc".

Table 24: Responses
Status Description Schema
200 A paginated response containing TEA Components paginated-component-response
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
Table 25: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.5.2 Get a TEA Component

GET/component/{uuid}

Get a TEA Component

Table 26: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Component in the TEA server
Table 27: Responses
Status Description Schema
200 Requested TEA Component found and returned component
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 28: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.6 TEA Component Release

8.6.1 List the releases of a TEA Component

GET/component/{uuid}/releases

Get releases of the component

Table 29: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Component in the TEA server
pageSize query No integer The maximum number of results to return.
Default: 25. Minimum: 1. Maximum: 100. Format: int64.
pageToken query No string

An opaque continuation token produced by a previous response. This token shall be copied verbatim from the nextPageToken value returned by the previous response. Clients shall not parse, construct, or modify this token.

The token represents continuation state for the original query, including sortField, sortOrder, result-affecting filters such as idType and idValue, and path parameters such as parent uuid. When pageToken is supplied, clients shall not change those result-affecting query parameters. Servers shall return 400 Bad Request if supplied result-affecting query parameters conflict with the token state. To change any result-affecting parameter, clients shall start a new pagination sequence without pageToken.

A pageToken is only valid with the same request path and same path parameter values used to obtain it. Clients shall not reuse a pageToken across different parent resource paths or different path uuid values. Servers shall return 400 Bad Request when a pageToken is used with a different path or different path parameter values.

Servers shall return 400 Bad Request for malformed, invalid, expired, or conflicting pageToken values.

sortField query No string (enum)

The field by which to sort the results.

Paginated results shall be ordered first by the selected sortField, then by uuid as a deterministic secondary tie-breaker.

When version is selected, ordering is by the stored version string according to the server's documented string collation; semantic-version precedence is not implied. Servers shall apply a stable and deterministic string collation for version sorting, and the same collation shall be used consistently across pages for a pagination sequence.

When releaseDate is selected, releases without a releaseDate shall be ordered consistently. Missing releaseDate values sort after populated releaseDate values for ascending order and before populated releaseDate values for descending order.

One of: createdDate, releaseDate, version. Default: "createdDate".

sortOrder query No string (enum)

The direction of the sort.

The default is asc for all paginated resources. Clients that need newest release or collection versions first can request sortOrder=desc.

The selected sort order applies to both the primary sortField and the resource-specific deterministic secondary tie-breaker. For products, components, product releases, and component releases, the secondary key is uuid. For collections, the secondary key is version if additional tie-breaking is needed.

One of: asc, desc. Default: "asc".

Table 30: Responses
Status Description Schema
200 A paginated response containing TEA Component Releases paginated-component-release-response
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 31: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.6.2 Query TEA Component Releases

GET/componentReleases

Returns a list of TEA component releases. Note that multiple component releases may match.

Table 32: Parameters
Name In Required Type Description
idType query No identifier-type Type of identifier specified in the idValue parameter
idValue query No string If present, only the objects with the given identifier value will be returned.
pageSize query No integer The maximum number of results to return.
Default: 25. Minimum: 1. Maximum: 100. Format: int64.
pageToken query No string

An opaque continuation token produced by a previous response. This token shall be copied verbatim from the nextPageToken value returned by the previous response. Clients shall not parse, construct, or modify this token.

The token represents continuation state for the original query, including sortField, sortOrder, result-affecting filters such as idType and idValue, and path parameters such as parent uuid. When pageToken is supplied, clients shall not change those result-affecting query parameters. Servers shall return 400 Bad Request if supplied result-affecting query parameters conflict with the token state. To change any result-affecting parameter, clients shall start a new pagination sequence without pageToken.

A pageToken is only valid with the same request path and same path parameter values used to obtain it. Clients shall not reuse a pageToken across different parent resource paths or different path uuid values. Servers shall return 400 Bad Request when a pageToken is used with a different path or different path parameter values.

Servers shall return 400 Bad Request for malformed, invalid, expired, or conflicting pageToken values.

sortField query No string (enum)

The field by which to sort the results.

Paginated results shall be ordered first by the selected sortField, then by uuid as a deterministic secondary tie-breaker.

When version is selected, ordering is by the stored version string according to the server's documented string collation; semantic-version precedence is not implied. Servers shall apply a stable and deterministic string collation for version sorting, and the same collation shall be used consistently across pages for a pagination sequence.

When releaseDate is selected, releases without a releaseDate shall be ordered consistently. Missing releaseDate values sort after populated releaseDate values for ascending order and before populated releaseDate values for descending order.

One of: createdDate, releaseDate, version. Default: "createdDate".

sortOrder query No string (enum)

The direction of the sort.

The default is asc for all paginated resources. Clients that need newest release or collection versions first can request sortOrder=desc.

The selected sort order applies to both the primary sortField and the resource-specific deterministic secondary tie-breaker. For products, components, product releases, and component releases, the secondary key is uuid. For collections, the secondary key is version if additional tie-breaking is needed.

One of: asc, desc. Default: "asc".

Table 33: Responses
Status Description Schema
200 A paginated response containing TEA Component Releases paginated-component-release-response
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
Table 34: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.6.3 Get a TEA Component Release with its latest collection

GET/componentRelease/{uuid}

Get the TEA Component Release with its latest collection

Table 35: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Component Release in the TEA server
Table 36: Responses
Status Description Schema
200 Requested TEA Component Release and its latest Collection found and returned component-release-with-collection
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 37: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.7 TEA Collection

8.7.1 List the collections of a TEA Product Release

GET/productRelease/{uuid}/collections

Get the TEA Collections belonging to the TEA Product Release

Table 38: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Product Release in the TEA server
pageSize query No integer The maximum number of results to return.
Default: 25. Minimum: 1. Maximum: 100. Format: int64.
pageToken query No string

An opaque continuation token produced by a previous response. This token shall be copied verbatim from the nextPageToken value returned by the previous response. Clients shall not parse, construct, or modify this token.

The token represents continuation state for the original query, including sortField, sortOrder, result-affecting filters such as idType and idValue, and path parameters such as parent uuid. When pageToken is supplied, clients shall not change those result-affecting query parameters. Servers shall return 400 Bad Request if supplied result-affecting query parameters conflict with the token state. To change any result-affecting parameter, clients shall start a new pagination sequence without pageToken.

A pageToken is only valid with the same request path and same path parameter values used to obtain it. Clients shall not reuse a pageToken across different parent resource paths or different path uuid values. Servers shall return 400 Bad Request when a pageToken is used with a different path or different path parameter values.

Servers shall return 400 Bad Request for malformed, invalid, expired, or conflicting pageToken values.

sortField query No string (enum)

The field by which to sort the results.

Paginated collection results shall be ordered first by the selected sortField, then by version as the deterministic secondary key if additional tie-breaking is needed. Collection UUIDs are not used as tie-breakers because collection UUIDs match the associated release UUID and can be shared across collection revisions.

The only currently supported collection sortField is version, so the secondary version key is redundant unless additional collection sort fields are added later.

One of: version. Default: "version".

sortOrder query No string (enum)

The direction of the sort.

The default is asc for all paginated resources. Clients that need newest release or collection versions first can request sortOrder=desc.

The selected sort order applies to both the primary sortField and the resource-specific deterministic secondary tie-breaker. For products, components, product releases, and component releases, the secondary key is uuid. For collections, the secondary key is version if additional tie-breaking is needed.

One of: asc, desc. Default: "asc".

Table 39: Responses
Status Description Schema
200 A paginated response containing TEA Collections paginated-collection-response
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 40: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.7.2 Get the latest collection of a TEA Product Release

GET/productRelease/{uuid}/collection/latest

Get the latest TEA Collection belonging to the TEA Product Release, that is, the collection with the greatest published version.

404 means the release is unknown; a release always has a latest collection.

Table 41: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Product Release in the TEA server
Table 42: Responses
Status Description Schema
200 Requested TEA Collection found and returned collection
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 43: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.7.3 Get one collection version of a TEA Product Release

GET/productRelease/{uuid}/collection/{collectionVersion}

Get a specific Collection (by version) for a TEA Product Release by its UUID

Table 44: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Product Release in the TEA server
collectionVersion path Yes integer Version of TEA Collection
Table 45: Responses
Status Description Schema
200 Requested TEA Collection Version found and returned collection
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 46: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.7.4 List the collections of a TEA Component Release

GET/componentRelease/{uuid}/collections

Get the TEA Collections belonging to the TEA Component Release

Table 47: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Component Release in the TEA server
pageSize query No integer The maximum number of results to return.
Default: 25. Minimum: 1. Maximum: 100. Format: int64.
pageToken query No string

An opaque continuation token produced by a previous response. This token shall be copied verbatim from the nextPageToken value returned by the previous response. Clients shall not parse, construct, or modify this token.

The token represents continuation state for the original query, including sortField, sortOrder, result-affecting filters such as idType and idValue, and path parameters such as parent uuid. When pageToken is supplied, clients shall not change those result-affecting query parameters. Servers shall return 400 Bad Request if supplied result-affecting query parameters conflict with the token state. To change any result-affecting parameter, clients shall start a new pagination sequence without pageToken.

A pageToken is only valid with the same request path and same path parameter values used to obtain it. Clients shall not reuse a pageToken across different parent resource paths or different path uuid values. Servers shall return 400 Bad Request when a pageToken is used with a different path or different path parameter values.

Servers shall return 400 Bad Request for malformed, invalid, expired, or conflicting pageToken values.

sortField query No string (enum)

The field by which to sort the results.

Paginated collection results shall be ordered first by the selected sortField, then by version as the deterministic secondary key if additional tie-breaking is needed. Collection UUIDs are not used as tie-breakers because collection UUIDs match the associated release UUID and can be shared across collection revisions.

The only currently supported collection sortField is version, so the secondary version key is redundant unless additional collection sort fields are added later.

One of: version. Default: "version".

sortOrder query No string (enum)

The direction of the sort.

The default is asc for all paginated resources. Clients that need newest release or collection versions first can request sortOrder=desc.

The selected sort order applies to both the primary sortField and the resource-specific deterministic secondary tie-breaker. For products, components, product releases, and component releases, the secondary key is uuid. For collections, the secondary key is version if additional tie-breaking is needed.

One of: asc, desc. Default: "asc".

Table 48: Responses
Status Description Schema
200 A paginated response containing TEA Collections paginated-collection-response
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 49: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.7.5 Get the latest collection of a TEA Component Release

GET/componentRelease/{uuid}/collection/latest

Get the latest TEA Collection belonging to the TEA Component Release, that is, the collection with the greatest published version.

404 means the release is unknown; a release always has a latest collection.

Table 50: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Component Release in the TEA server
Table 51: Responses
Status Description Schema
200 Requested TEA Collection found and returned collection
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 52: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.7.6 Get one collection version of a TEA Component Release

GET/componentRelease/{uuid}/collection/{collectionVersion}

Get a specific Collection (by version) for a TEA Component Release by its UUID

Table 53: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Component Release in the TEA server
collectionVersion path Yes integer Version of TEA Collection
Table 54: Responses
Status Description Schema
200 Requested TEA Collection Version found and returned collection
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 55: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.8 TEA Artifact

8.8.1 Get the metadata of the latest TEA Artifact revision

GET/artifact/{uuid}/latest

Get metadata for the latest revision of a specific TEA Artifact, that is, the revision with the greatest published version.

Table 56: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Artifact in the TEA server
Table 57: Responses
Status Description Schema
200 Requested TEA Artifact metadata found and returned artifact
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 58: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.8.2 Download the content of the latest TEA Artifact revision

GET/artifact/{uuid}/latest/download

Download the content of the latest revision of a specific TEA Artifact.

Equivalent to the versioned download endpoint, resolving to the revision with the greatest published version — the same revision /artifact/{uuid}/latest reports. The content this returns changes when a new revision is published, so unlike the versioned endpoint the response is not immutable: caches shall revalidate it via ETag for the HTTP representation selected after negotiation. The Content-Location header is an absolute versioned URL including the API base, version path, and mediaType query parameter. That URL identifies the revision and format; HTTP content coding can still be negotiated.

When serving the content itself (200), servers shall return a strong ETag for the HTTP representation selected after negotiation, including content coding, and shall honor If-None-Match with 304. ETag is the only conditional validator for these downloads. Servers that support HEAD for this operation shall return the same headers as GET without a response body. 302 redirects are outside conditional semantics: If-None-Match applies only to the TEA-hosted download response, not to following an external Location.

Table 59: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Artifact in the TEA server
mediaType query No string

Selects which of the artifact revision's formats to return, by its mediaType. The parameter value is the media type itself (for example application/vnd.cyclonedx+json), not a pre-encoded wire form. Clients shall apply query-parameter serialization once. Servers shall interpret the value after one query-decoding step.

Matching against a format's mediaType is case-insensitive for the type and subtype. Parameter names are compared case-insensitively; parameter values require exact equality. When omitted, the server selects a format using the request's Accept header per RFC 9110 section 12, and falls back to a format of its choice when Accept does not constrain the result. In either case the Content-Type of the response states which format was returned. An explicit mediaType can remove variation by Accept when it completely determines the format. When it does not, the server shall include Accept in Vary if changing or removing Accept could change the selected format, including when Accept is absent or contains */*. A mediaType query parameter does not eliminate variation by Accept-Encoding; see artifact-vary.

Example after serialization: .../download?mediaType=application%2Fvnd.cyclonedx%2Bjson

If-None-Match header No string Conditional request validator (RFC 9110). For artifact and signature downloads, ETag is the only defined validator. Servers evaluate If-None-Match with the weak comparison function (RFC 9110 section 13.1.2) against the ETag of the representation selected after negotiation, including content-coding negotiation, and answer 304 when it matches. The corresponding 304 shall carry that representation's validator and shall carry Vary when the 200 would. When present, that ETag is a strong validator. Other validators are not defined for these operations.
Table 60: Responses
Status Description Schema
200

The content of the selected format of the latest revision of the TEA Artifact, as resolved at the time of the request.

Identical to artifact-content except for its cache policy: the latest revision changes when a new revision is published, so the response is not immutable and a cache shall revalidate it before reuse. Servers shall return a strong ETag for the selected HTTP representation. Revalidation returns 304 Not Modified when If-None-Match matches that representation's validator. Content-Location identifies the revision and format. Vary follows the same rules as artifact-content.

string
302

The selected representation is available at another location, for example object storage addressed by a pre-signed URL. The client follows the Location header.

Changing only this response's Location, while preserving the artifact or signature bytes for the selected UUID, version, and format after HTTP content coding is removed, does not require a new artifact or collection version. Publishing a different external url or signatureUrl on the artifact metadata is a separate change and shall follow the artifact-format rules for those fields.

A client shall not send its TEA access token when following a redirect to a different origin.

—
304 The representation selected after negotiation has not changed (RFC 9110). The response body is empty. Servers shall repeat ETag and Content-Location from the would-be successful response for that representation, and shall repeat Cache-Control and Vary when the corresponding 200 carries them. —
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
406

The artifact revision exists, but has no format matching the requested mediaType or Accept header. Body is a TEA error-response with error: NO_ACCEPTABLE_FORMAT.

NO_ACCEPTABLE_FORMAT reveals that the artifact revision exists. A server concealing an artifact from a client shall answer 404 with error: OBJECT_UNKNOWN for every sub-resource of it, formats included, instead of this status.

error-response
Table 61: Response headers
Status Header Type Description
200 Content-Disposition string Suggested filename for the artifact content, as an attachment disposition per RFC 6266.
200 Content-Encoding string HTTP content codings applied to the selected representation, listed in the order applied (RFC 9110). When no content coding is applied, the server should omit this header. An artifact's own compression, such as a .gz file, is not HTTP content coding and shall not be declared here.
200 ETag string

The server shall provide a strong entity tag for the selected HTTP representation. Representations with different bytes shall have different strong entity tags, including representations that differ because of HTTP content coding. Artifact revision immutability does not require all HTTP representations of that revision to share an entity tag.

Intermediaries that compress on the fly often weaken the entity tag, which does not meet this requirement. Servers that offer content coding can serve precompressed variants, or assign their own strong entity tag to each coded representation.

200 Cache-Control string

The latest revision is a moving target: which revision it resolves to changes when a new revision is published. Servers shall not mark it immutable and shall require revalidation, so that a cache reuses a stored representation only after confirming, through that representation's ETag, that the selected representation has not changed.

As with versioned downloads, responses containing access-controlled content shall use private or no-store (for example private, no-cache). Servers shall use public only for content available without authorization.

200 Content-Location string Absolute URL of the versioned content download for the revision and format this response was resolved to, per RFC 9110 section 8.7. It includes the TEA API base, version path, and a mediaType query parameter naming the selected format. The URL identifies the revision and format. HTTP content coding can still be negotiated on a follow-up GET. A client that needs a stable reference to that revision and format uses this URL rather than the latest URL.
Format: uri.
200 Vary string

If changing or removing the Accept request header could change the selected format for the same target URI, the server shall include Accept in Vary, including when Accept is absent or contains */* (RFC 9110 section 12.5.5). An explicit mediaType query parameter can remove variation by Accept when it completely determines the format.

If changing or removing the Accept-Encoding request header could change the selected content coding for the same target URI, the server shall include Accept-Encoding in Vary, including when Accept-Encoding is absent or the selected response uses no content coding. A mediaType query parameter does not eliminate variation by encoding.

200 Repr-Digest string When provided, Repr-Digest shall contain a digest of the complete selected HTTP representation data, including any applied content coding and excluding transfer coding, as defined in RFC 9530. It does not replace verification against the published checksums in the artifact metadata.
302 Location string Location the selected representation can be retrieved from.
Format: uri.
304 ETag string Same ETag the server would have sent on 200 for this operation.
304 Cache-Control string Same Cache-Control the server would have sent on 200 for this operation.
304 Content-Location string Same Content-Location the server would have sent on 200 for this operation.
Format: uri.
304 Vary string Same Vary the server would have sent on 200 for this operation, when used.
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.8.3 Download the signature of the latest TEA Artifact revision

GET/artifact/{uuid}/latest/signature/download

Download the detached signature for the latest revision of a specific TEA Artifact.

Equivalent to the versioned signature endpoint, resolving to the revision with the greatest published version — the same revision /artifact/{uuid}/latest reports. As with the latest content endpoint, the response is not immutable and caches shall revalidate it via ETag for the HTTP representation selected after negotiation. Content-Location is an absolute versioned signature URL including the API base, version path, and mediaType query parameter. That URL identifies the revision and format; HTTP content coding can still be negotiated.

When serving the signature itself (200), servers shall return a strong ETag for the HTTP representation selected after negotiation, including content coding, and shall honor If-None-Match with 304. ETag is the only conditional validator for these downloads. Servers that support HEAD for this operation shall return the same headers as GET without a response body. 302 redirects are outside conditional semantics: If-None-Match applies only to the TEA-hosted download response, not to following an external Location.

404 distinguishes the cases by TEA error body: OBJECT_UNKNOWN when the artifact revision is unknown (or concealed), and SIGNATURE_NOT_FOUND when the revision exists but the selected format has no signature published. A server concealing an artifact from a client shall answer OBJECT_UNKNOWN for every sub-resource of it, including signatures.

Table 62: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Artifact in the TEA server
mediaType query No string

Selects which of the artifact revision's formats the returned signature applies to, by that format's mediaType. This is the media type of the signed content, not of the signature. The parameter value is the media type itself, not a pre-encoded wire form. Clients shall apply query-parameter serialization once. Servers shall interpret the value after one query-decoding step.

Matching against a format's mediaType is case-insensitive for the type and subtype. Parameter names are compared case-insensitively; parameter values require exact equality. When omitted, the server selects a format of its choice. Requests that need a specific format's signature should supply this parameter. Successful responses include Content-Location with a mediaType query parameter naming the selected content format. An explicit mediaType can remove variation by Accept when it completely determines the signed format. It does not eliminate variation by Accept-Encoding; see artifact-vary.

Example after serialization: .../signature/download?mediaType=application%2Fvnd.cyclonedx%2Bjson

If-None-Match header No string Conditional request validator (RFC 9110). For artifact and signature downloads, ETag is the only defined validator. Servers evaluate If-None-Match with the weak comparison function (RFC 9110 section 13.1.2) against the ETag of the representation selected after negotiation, including content-coding negotiation, and answer 304 when it matches. The corresponding 304 shall carry that representation's validator and shall carry Vary when the 200 would. When present, that ETag is a strong validator. Other validators are not defined for these operations.
Table 63: Responses
Status Description Schema
200

The detached signature for the selected format of the latest revision of the TEA Artifact, as resolved at the time of the request.

Identical to artifact-signature-content except for its cache policy: the latest revision changes when a new revision is published, so the response is not immutable and a cache shall revalidate it before reuse. Servers shall return a strong ETag for the selected HTTP representation. Revalidation returns 304 Not Modified when If-None-Match matches that representation's validator. Content-Location identifies the revision and format. Vary follows the same rules as artifact-signature-content.

string
302

The selected representation is available at another location, for example object storage addressed by a pre-signed URL. The client follows the Location header.

Changing only this response's Location, while preserving the artifact or signature bytes for the selected UUID, version, and format after HTTP content coding is removed, does not require a new artifact or collection version. Publishing a different external url or signatureUrl on the artifact metadata is a separate change and shall follow the artifact-format rules for those fields.

A client shall not send its TEA access token when following a redirect to a different origin.

—
304 The representation selected after negotiation has not changed (RFC 9110). The response body is empty. Servers shall repeat ETag and Content-Location from the would-be successful response for that representation, and shall repeat Cache-Control and Vary when the corresponding 200 carries them. —
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
406

The artifact revision exists, but has no format matching the requested mediaType or Accept header. Body is a TEA error-response with error: NO_ACCEPTABLE_FORMAT.

NO_ACCEPTABLE_FORMAT reveals that the artifact revision exists. A server concealing an artifact from a client shall answer 404 with error: OBJECT_UNKNOWN for every sub-resource of it, formats included, instead of this status.

error-response
Table 64: Response headers
Status Header Type Description
200 Content-Disposition string Suggested filename for the signature, as an attachment disposition per RFC 6266.
200 Content-Encoding string HTTP content codings applied to the selected representation, listed in the order applied (RFC 9110). When no content coding is applied, the server should omit this header. An artifact's own compression, such as a .gz file, is not HTTP content coding and shall not be declared here.
200 ETag string The server shall provide a strong entity tag for the selected HTTP representation. Representations with different bytes shall have different strong entity tags, including representations that differ because of HTTP content coding. Artifact revision immutability does not require all HTTP representations of that revision to share an entity tag. Content that is re-signed is published as a new revision. On-the-fly compression follows artifact-etag.
200 Cache-Control string

The latest revision is a moving target: which revision it resolves to changes when a new revision is published. Servers shall not mark it immutable and shall require revalidation, so that a cache reuses a stored representation only after confirming, through that representation's ETag, that the selected representation has not changed.

As with versioned downloads, responses containing access-controlled content shall use private or no-store (for example private, no-cache). Servers shall use public only for content available without authorization.

200 Content-Location string Absolute URL of the versioned signature download for the revision and format this response was resolved to, per RFC 9110 section 8.7. It includes the TEA API base, version path, and a mediaType query parameter naming the selected content format. The URL identifies the revision and format. HTTP content coding can still be negotiated on a follow-up GET.
Format: uri.
200 Vary string

If changing or removing the Accept request header could change the selected format for the same target URI, the server shall include Accept in Vary, including when Accept is absent or contains */* (RFC 9110 section 12.5.5). An explicit mediaType query parameter can remove variation by Accept when it completely determines the format.

If changing or removing the Accept-Encoding request header could change the selected content coding for the same target URI, the server shall include Accept-Encoding in Vary, including when Accept-Encoding is absent or the selected response uses no content coding. A mediaType query parameter does not eliminate variation by encoding.

200 Repr-Digest string When provided, Repr-Digest shall contain a digest of the complete selected HTTP representation data, including any applied content coding and excluding transfer coding, as defined in RFC 9530. It does not replace verification against the published checksums in the artifact metadata.
302 Location string Location the selected representation can be retrieved from.
Format: uri.
304 ETag string Same ETag the server would have sent on 200 for this operation.
304 Cache-Control string Same Cache-Control the server would have sent on 200 for this operation.
304 Content-Location string Same Content-Location the server would have sent on 200 for this operation.
Format: uri.
304 Vary string Same Vary the server would have sent on 200 for this operation, when used.
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.8.4 Get the metadata of one TEA Artifact revision

GET/artifact/{uuid}/{artifactVersion}

Get metadata for a specific revision of a specific TEA Artifact

Table 65: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Artifact in the TEA server
artifactVersion path Yes integer Version of TEA Artifact
Table 66: Responses
Status Description Schema
200 Requested TEA Artifact metadata found and returned artifact
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 67: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.8.5 Download the content of one TEA Artifact revision

GET/artifact/{uuid}/{artifactVersion}/download

Download the content of a specific revision of a specific TEA Artifact.

This endpoint returns the bytes of one format of the artifact revision. It is how a TEA server hosts artifact content itself: a format that has no external url is retrieved from here, selected by its mediaType. A format that has a url is retrieved from that external location instead, and this endpoint is not required to serve it.

A TEA access token is sent only to the TEA server's own API base URL. External url targets are retrieved without it. They are openly accessible or require credentials the client arranges separately. Expiring storage links should not be published in url; the server answers from this endpoint, including with 302.

When serving the content itself (200), servers shall return a strong ETag for the HTTP representation selected after negotiation, including content coding, and shall honor If-None-Match with 304. ETag is the only conditional validator for these downloads. Servers that support HEAD for this operation shall return the same headers as GET without a response body. 302 redirects are outside conditional semantics: If-None-Match applies only to the TEA-hosted download response, not to following an external Location.

How long a cache may retain the response depends on whether the content is publicly accessible: see artifact-cache-control-immutable. Immutability does not imply that shared caches may store access-controlled responses. Successful responses include Content-Location as an absolute URL of this versioned download including the mediaType query parameter. That URL identifies the revision and format; HTTP content coding can still be negotiated.

Table 68: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Artifact in the TEA server
artifactVersion path Yes integer Version of TEA Artifact
mediaType query No string

Selects which of the artifact revision's formats to return, by its mediaType. The parameter value is the media type itself (for example application/vnd.cyclonedx+json), not a pre-encoded wire form. Clients shall apply query-parameter serialization once. Servers shall interpret the value after one query-decoding step.

Matching against a format's mediaType is case-insensitive for the type and subtype. Parameter names are compared case-insensitively; parameter values require exact equality. When omitted, the server selects a format using the request's Accept header per RFC 9110 section 12, and falls back to a format of its choice when Accept does not constrain the result. In either case the Content-Type of the response states which format was returned. An explicit mediaType can remove variation by Accept when it completely determines the format. When it does not, the server shall include Accept in Vary if changing or removing Accept could change the selected format, including when Accept is absent or contains */*. A mediaType query parameter does not eliminate variation by Accept-Encoding; see artifact-vary.

Example after serialization: .../download?mediaType=application%2Fvnd.cyclonedx%2Bjson

If-None-Match header No string Conditional request validator (RFC 9110). For artifact and signature downloads, ETag is the only defined validator. Servers evaluate If-None-Match with the weak comparison function (RFC 9110 section 13.1.2) against the ETag of the representation selected after negotiation, including content-coding negotiation, and answer 304 when it matches. The corresponding 304 shall carry that representation's validator and shall carry Vary when the 200 would. When present, that ETag is a strong validator. Other validators are not defined for these operations.
Table 69: Responses
Status Description Schema
200

The content of the requested TEA Artifact format.

The wire Content-Type is the mediaType of the format returned. The response content key is */* because that type varies by format. Content-Encoding, when present, names the HTTP content coding of the selected representation. Content-Location identifies the revision and format; HTTP content coding can still be negotiated. Vary follows artifact-vary.

string
302

The selected representation is available at another location, for example object storage addressed by a pre-signed URL. The client follows the Location header.

Changing only this response's Location, while preserving the artifact or signature bytes for the selected UUID, version, and format after HTTP content coding is removed, does not require a new artifact or collection version. Publishing a different external url or signatureUrl on the artifact metadata is a separate change and shall follow the artifact-format rules for those fields.

A client shall not send its TEA access token when following a redirect to a different origin.

—
304 The representation selected after negotiation has not changed (RFC 9110). The response body is empty. Servers shall repeat ETag and Content-Location from the would-be successful response for that representation, and shall repeat Cache-Control and Vary when the corresponding 200 carries them. —
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
406

The artifact revision exists, but has no format matching the requested mediaType or Accept header. Body is a TEA error-response with error: NO_ACCEPTABLE_FORMAT.

NO_ACCEPTABLE_FORMAT reveals that the artifact revision exists. A server concealing an artifact from a client shall answer 404 with error: OBJECT_UNKNOWN for every sub-resource of it, formats included, instead of this status.

error-response
Table 70: Response headers
Status Header Type Description
200 Content-Disposition string Suggested filename for the artifact content, as an attachment disposition per RFC 6266.
200 Content-Encoding string HTTP content codings applied to the selected representation, listed in the order applied (RFC 9110). When no content coding is applied, the server should omit this header. An artifact's own compression, such as a .gz file, is not HTTP content coding and shall not be declared here.
200 ETag string

The server shall provide a strong entity tag for the selected HTTP representation. Representations with different bytes shall have different strong entity tags, including representations that differ because of HTTP content coding. Artifact revision immutability does not require all HTTP representations of that revision to share an entity tag.

Intermediaries that compress on the fly often weaken the entity tag, which does not meet this requirement. Servers that offer content coding can serve precompressed variants, or assign their own strong entity tag to each coded representation.

200 Cache-Control string

Cache policy for a specific artifact or signature revision. Artifact and signature bytes remain unchanged after HTTP decoding. A server may use immutable only when the selected HTTP representation, including its content-coded bytes, will remain unchanged throughout the response's freshness lifetime. Otherwise, the server shall omit immutable.

Responses containing access-controlled content shall use Cache-Control private or no-store. Servers shall use public only for content available without authorization. Immutability does not imply public accessibility (see RFC 9111 section 5.2.2.9).

200 Content-Location string Absolute URL of the versioned content download for the revision and format this response was resolved to, per RFC 9110 section 8.7. It includes the TEA API base, version path, and a mediaType query parameter naming the selected format. The URL identifies the revision and format. HTTP content coding can still be negotiated on a follow-up GET. A client that needs a stable reference to that revision and format uses this URL rather than the latest URL.
Format: uri.
200 Vary string

If changing or removing the Accept request header could change the selected format for the same target URI, the server shall include Accept in Vary, including when Accept is absent or contains */* (RFC 9110 section 12.5.5). An explicit mediaType query parameter can remove variation by Accept when it completely determines the format.

If changing or removing the Accept-Encoding request header could change the selected content coding for the same target URI, the server shall include Accept-Encoding in Vary, including when Accept-Encoding is absent or the selected response uses no content coding. A mediaType query parameter does not eliminate variation by encoding.

200 Repr-Digest string When provided, Repr-Digest shall contain a digest of the complete selected HTTP representation data, including any applied content coding and excluding transfer coding, as defined in RFC 9530. It does not replace verification against the published checksums in the artifact metadata.
302 Location string Location the selected representation can be retrieved from.
Format: uri.
304 ETag string Same ETag the server would have sent on 200 for this operation.
304 Cache-Control string Same Cache-Control the server would have sent on 200 for this operation.
304 Content-Location string Same Content-Location the server would have sent on 200 for this operation.
Format: uri.
304 Vary string Same Vary the server would have sent on 200 for this operation, when used.
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.8.6 Download the signature of one TEA Artifact revision

GET/artifact/{uuid}/{artifactVersion}/signature/download

Download the detached signature for one format of a specific revision of a specific TEA Artifact.

This is the counterpart of the artifact content endpoint, for TEA servers that host signatures themselves: a format that has no external signatureUrl is retrieved from here, selected by its mediaType. A format that has a signatureUrl is retrieved from that external location instead, and this endpoint is not required to serve it.

Signatures are per format: each format of a revision is a distinct sequence of bytes and therefore has its own signature. The mediaType parameter selects which format's signature is returned, not the format of the signature itself.

This specification makes no assumption about the signature technology in use, and does not model the signing algorithm, key, or certificate chain; the response is the signature as published. A client that cannot determine how to verify what it receives should treat the signature as unusable rather than as invalid.

404 distinguishes the cases by TEA error body: OBJECT_UNKNOWN when the artifact revision is unknown (or concealed), and SIGNATURE_NOT_FOUND when the revision exists but the selected format has no signature published. A server concealing an artifact from a client shall answer OBJECT_UNKNOWN for every sub-resource of it, including signatures.

When serving the signature itself (200), servers shall return a strong ETag for the HTTP representation selected after negotiation, including content coding, and shall honor If-None-Match with 304. ETag is the only conditional validator for these downloads. Servers that support HEAD for this operation shall return the same headers as GET without a response body. 302 redirects are outside conditional semantics: If-None-Match applies only to the TEA-hosted download response, not to following an external Location. Successful responses include Content-Location as an absolute URL of this versioned signature download including the mediaType query parameter. That URL identifies the revision and format; HTTP content coding can still be negotiated.

Table 71: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Artifact in the TEA server
artifactVersion path Yes integer Version of TEA Artifact
mediaType query No string

Selects which of the artifact revision's formats the returned signature applies to, by that format's mediaType. This is the media type of the signed content, not of the signature. The parameter value is the media type itself, not a pre-encoded wire form. Clients shall apply query-parameter serialization once. Servers shall interpret the value after one query-decoding step.

Matching against a format's mediaType is case-insensitive for the type and subtype. Parameter names are compared case-insensitively; parameter values require exact equality. When omitted, the server selects a format of its choice. Requests that need a specific format's signature should supply this parameter. Successful responses include Content-Location with a mediaType query parameter naming the selected content format. An explicit mediaType can remove variation by Accept when it completely determines the signed format. It does not eliminate variation by Accept-Encoding; see artifact-vary.

Example after serialization: .../signature/download?mediaType=application%2Fvnd.cyclonedx%2Bjson

If-None-Match header No string Conditional request validator (RFC 9110). For artifact and signature downloads, ETag is the only defined validator. Servers evaluate If-None-Match with the weak comparison function (RFC 9110 section 13.1.2) against the ETag of the representation selected after negotiation, including content-coding negotiation, and answer 304 when it matches. The corresponding 304 shall carry that representation's validator and shall carry Vary when the 200 would. When present, that ETag is a strong validator. Other validators are not defined for these operations.
Table 72: Responses
Status Description Schema
200

The detached signature for the selected format of the TEA Artifact revision.

The wire Content-Type is application/octet-stream unless the server knows a more specific media type for the signature it holds, in which case it returns that. The response content key is */* because that type may vary. This specification does not require servers to identify the signature technology. Content-Encoding, when present, names the HTTP content coding of the selected representation. Content-Location identifies the revision and format; HTTP content coding can still be negotiated. Vary follows artifact-vary.

string
302

The selected representation is available at another location, for example object storage addressed by a pre-signed URL. The client follows the Location header.

Changing only this response's Location, while preserving the artifact or signature bytes for the selected UUID, version, and format after HTTP content coding is removed, does not require a new artifact or collection version. Publishing a different external url or signatureUrl on the artifact metadata is a separate change and shall follow the artifact-format rules for those fields.

A client shall not send its TEA access token when following a redirect to a different origin.

—
304 The representation selected after negotiation has not changed (RFC 9110). The response body is empty. Servers shall repeat ETag and Content-Location from the would-be successful response for that representation, and shall repeat Cache-Control and Vary when the corresponding 200 carries them. —
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
406

The artifact revision exists, but has no format matching the requested mediaType or Accept header. Body is a TEA error-response with error: NO_ACCEPTABLE_FORMAT.

NO_ACCEPTABLE_FORMAT reveals that the artifact revision exists. A server concealing an artifact from a client shall answer 404 with error: OBJECT_UNKNOWN for every sub-resource of it, formats included, instead of this status.

error-response
Table 73: Response headers
Status Header Type Description
200 Content-Disposition string Suggested filename for the signature, as an attachment disposition per RFC 6266.
200 Content-Encoding string HTTP content codings applied to the selected representation, listed in the order applied (RFC 9110). When no content coding is applied, the server should omit this header. An artifact's own compression, such as a .gz file, is not HTTP content coding and shall not be declared here.
200 ETag string The server shall provide a strong entity tag for the selected HTTP representation. Representations with different bytes shall have different strong entity tags, including representations that differ because of HTTP content coding. Artifact revision immutability does not require all HTTP representations of that revision to share an entity tag. Content that is re-signed is published as a new revision. On-the-fly compression follows artifact-etag.
200 Cache-Control string

Cache policy for a specific artifact or signature revision. Artifact and signature bytes remain unchanged after HTTP decoding. A server may use immutable only when the selected HTTP representation, including its content-coded bytes, will remain unchanged throughout the response's freshness lifetime. Otherwise, the server shall omit immutable.

Responses containing access-controlled content shall use Cache-Control private or no-store. Servers shall use public only for content available without authorization. Immutability does not imply public accessibility (see RFC 9111 section 5.2.2.9).

200 Content-Location string Absolute URL of the versioned signature download for the revision and format this response was resolved to, per RFC 9110 section 8.7. It includes the TEA API base, version path, and a mediaType query parameter naming the selected content format. The URL identifies the revision and format. HTTP content coding can still be negotiated on a follow-up GET.
Format: uri.
200 Vary string

If changing or removing the Accept request header could change the selected format for the same target URI, the server shall include Accept in Vary, including when Accept is absent or contains */* (RFC 9110 section 12.5.5). An explicit mediaType query parameter can remove variation by Accept when it completely determines the format.

If changing or removing the Accept-Encoding request header could change the selected content coding for the same target URI, the server shall include Accept-Encoding in Vary, including when Accept-Encoding is absent or the selected response uses no content coding. A mediaType query parameter does not eliminate variation by encoding.

200 Repr-Digest string When provided, Repr-Digest shall contain a digest of the complete selected HTTP representation data, including any applied content coding and excluding transfer coding, as defined in RFC 9530. It does not replace verification against the published checksums in the artifact metadata.
302 Location string Location the selected representation can be retrieved from.
Format: uri.
304 ETag string Same ETag the server would have sent on 200 for this operation.
304 Cache-Control string Same Cache-Control the server would have sent on 200 for this operation.
304 Content-Location string Same Content-Location the server would have sent on 200 for this operation.
Format: uri.
304 Vary string Same Vary the server would have sent on 200 for this operation, when used.
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.9 CLE

8.9.1 Get the lifecycle events of a TEA Product

GET/product/{uuid}/cle

Get the CLE (Common Lifecycle Enumeration) data for a TEA Product

Table 74: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Product in the TEA server
Table 75: Responses
Status Description Schema
200 CLE data for the requested TEA Product found and returned cle
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 76: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.9.2 Get the lifecycle events of a TEA Product Release

GET/productRelease/{uuid}/cle

Get the CLE (Common Lifecycle Enumeration) data for a TEA Product Release

Table 77: Parameters
Name In Required Type Description
uuid path Yes uuid Unique UUID of TEA Product Release in the TEA server
Table 78: Responses
Status Description Schema
200 CLE data for the requested TEA Product Release found and returned cle
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 79: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.9.3 Get the lifecycle events of a TEA Component

GET/component/{uuid}/cle

Get the CLE (Common Lifecycle Enumeration) data for a TEA Component

Table 80: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Component in the TEA server
Table 81: Responses
Status Description Schema
200 CLE data for the requested TEA Component found and returned cle
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 82: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.

8.9.4 Get the lifecycle events of a TEA Component Release

GET/componentRelease/{uuid}/cle

Get the CLE (Common Lifecycle Enumeration) data for a TEA Component Release

Table 83: Parameters
Name In Required Type Description
uuid path Yes uuid UUID of TEA Component Release in the TEA server
Table 84: Responses
Status Description Schema
200 CLE data for the requested TEA Component Release found and returned cle
400 Request was invalid. For paginated requests, this includes malformed, invalid, expired, or conflicting pageToken values, including conflicts with continuation parameters or path parameters (error: INVALID_PAGE_TOKEN when a TEA error body is present). Other malformed requests may use error: INVALID_REQUEST. error-response
401

Authentication required, or the presented access token is expired, revoked, or otherwise invalid. Servers shall include a WWW-Authenticate header as defined in RFC 6750 section 3. On the invalid_token error a client may obtain a fresh token from /token and retry the request once (RFC 6750 section 3.1). The WWW-Authenticate challenge remains the primary signal; an error-response body is optional.

Servers that require no authentication on any endpoint shall not return this status. On a TEA server where some data is available without authentication, but not all, protected endpoints return 401 when no valid token is presented; endpoints that do not require authentication answer without requiring a Bearer token. A protected object shall not answer 404 solely because the client is unauthenticated: absence of a valid token yields 401, so the client flow can discover that authentication is required.

error-response
403

The client is authenticated, but is not authorized to access this resource or perform this operation. Authorization decisions are server-specific and are not constrained by this specification.

Servers may instead conceal the existence of a resource from an authenticated but unauthorized client by answering 404 (see 404-object-by-id-not-found). Clients shall treat 403 and that concealing 404 as non-access; neither implies that retrying with the same token will succeed.

error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 85: Response headers
Status Header Type Description
401 WWW-Authenticate string Bearer challenge, as defined in RFC 6750 section 3.
Normative Optional

8.10 TEA Authentication

8.10.1 Exchange credentials for a TEA access token

POST/token

Exchange credentials for a TEA access token.

A TEA server that requires authentication on any of its endpoints shall implement this endpoint, and shall support the client_credentials grant type with HTTP Basic client authentication (RFC 6749 section 2.3.1, RFC 7617): the API key identifier is sent as the user-id and the API key secret as the password. A server that requires no authentication need not implement it.

Clients do not probe this endpoint to discover whether authentication is required: they issue the resource request, and a 401 response carrying a WWW-Authenticate: Bearer challenge is the signal to obtain a token here. A 404 from this endpoint, with or without a TEA error body, means only that it is not implemented. A server that mounts the path without implementing the exchange should answer with the shared object-not-found response and error: NOT_IMPLEMENTED.

Servers may support additional grant types for federated identity, for example SAML 2.0 assertions (RFC 7522) or JWT assertions (RFC 7523), and may authenticate the client with mutual TLS (RFC 8705) instead of Basic. Whichever grant type is used, the token returned by this endpoint is the only credential accepted on the other TEA endpoints.

RFC 8693 token exchange (urn:ietf:params:oauth:grant-type:token-exchange) is outside the scope of the TEA 1.0 interoperable authentication profile. TEA 1.0 does not specify the request or response contract for this grant. Implementations may support it as an extension by separate agreement, but clients shall not assume its availability based solely on TEA 1.0 conformance. Such extensions do not remove the requirement for servers requiring authentication to support the client_credentials baseline.

The access token is opaque to the client: clients shall not inspect, parse, or depend on its contents.

The empty security requirement on this operation does not authorize anonymous client_credentials issuance. It only allows the alternate client-authentication methods described above (for example, mutual TLS, JWT client assertion (RFC 7523), or credentials in the request body). For the baseline client_credentials grant with HTTP Basic, unauthenticated requests shall not be accepted: servers shall respond with 401, error: invalid_client, and a WWW-Authenticate: Basic challenge (see 401-token-error; RFC 6749 section 5.2).

Security: basicAuth or none (anonymous access)

Request body:

application/x-www-form-urlencoded—token-request (required)

Table 86: Responses
Status Description Schema
200 Credentials accepted, access token issued token-response
400 The token request was malformed, used an unsupported grant type, or the credentials presented were not valid for the requested grant. token-error-response
401 Client authentication failed (error: invalid_client). Returned instead of 400 when the client attempted to authenticate using the Authorization header (RFC 6749 section 5.2). For the baseline Basic exchange this includes a missing or invalid Authorization: Basic credential. Servers shall include WWW-Authenticate: Basic. token-error-response
404

Either the object is unknown to this server, or — where an endpoint documents it — the server does not provide an optional capability or sub-resource for that object. The cases are told apart by the TEA error body, never by the status alone:

  • error: OBJECT_UNKNOWN — no such object (or its existence is concealed from this client).
  • error: NOT_IMPLEMENTED — optional capability or endpoint not provided (for CLE: lifecycle data; for /token: the token endpoint is not implemented). CLE is optional in TEA; clients shall not treat this as a failure of the object itself where the capability is optional.
  • error: SIGNATURE_NOT_FOUND — the artifact revision and format exist, but no signature is published for that format. This reveals that the artifact exists; a server concealing an artifact shall answer OBJECT_UNKNOWN for every sub-resource of it, signatures included.

Concealment applies only after authentication. A request to a protected object with no valid access token shall receive 401 (see 401-unauthorized), not a concealing 404. Clients shall not infer from 404 alone whether the object is absent, withheld, or lacking an optional capability or sub-resource.

error-response
Table 87: Response headers
Status Header Type Description
200 Cache-Control string Servers shall set no-store on token responses (RFC 6749 section 5.1).
401 WWW-Authenticate string Challenge indicating the client authentication methods supported by the token endpoint.

9 Data model

This section catalogues the named schemas declared in components.schemas.

9.1 artifact

A security-related document

Type: object

Table 88: Properties
Property Type Requirement Description
uuid uuid Required The UUID of the TEA Artifact object. Together with version uniquely identifies the TEA Artifact.
version integer Required Revision number, starting at 1 and incremented by 1 for each new revision of the same artifact UUID. Together with uuid uniquely identifies the TEA Artifact. Successive revisions cover content changes and changes to any published field, including external url or signatureUrl values. Each published revision is immutable. For a fixed artifact UUID, version, and format, the server shall ensure that successful content retrieval through its download endpoint, including retrieval after following redirects, yields unchanged artifact bytes after HTTP transfer coding and content coding are removed, and that successful signature retrieval through its signature download endpoint yields unchanged signature bytes on the same terms. Changing only a download response's Location, or only its HTTP content coding, while preserving those bytes, does not require a new artifact or collection version.
name string Optional A human-readable name for the artefact
type artifact-type Required Type of TEA Artifact
createdDate date-time Required The date and time the TEA Artifact revision was created.
distributionIds Array of uuid Optional Array of TEA Component Release distributions that this TEA Artifact applies to. If absent or empty, the TEA Artifact applies to all distributions.
formats Array of artifact-format Required List of objects with the same content, but in different formats. The order of the list has no significance.
Example 1 (Informative)
{
  "uuid": "1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce",
  "version": 2,
  "name": "Build SBOM",
  "type": "BOM",
  "createdDate": "2024-12-13T00:00:00.000Z",
  "formats": [
    {
      "mediaType": "application/vnd.cyclonedx+xml",
      "description": "CycloneDX SBOM (XML)",
      "url": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml.asc",
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "e04c9d55986d7194822eaa4f8115a77f801844d807ad6e0d454ac31dd41861e5"
        },
        {
          "algType": "SHA-1",
          "algValue": "5a7d4caef63c5c5ccdf07c39337323529eb5a770"
        }
      ]
    }
  ]
}
Example 2 (Informative)
{
  "uuid": "dfa35519-9734-4259-bba1-3e825cf4be06",
  "version": 7,
  "name": "Vulnerability Disclosure Report",
  "type": "VULNERABILITIES",
  "createdDate": "2024-12-15T00:00:00.000Z",
  "formats": [
    {
      "mediaType": "application/vnd.cyclonedx+xml",
      "description": "CycloneDX VDR (XML)",
      "url": "https://logging.apache.org/cyclonedx/vdr.xml",
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "75b81020b3917cb682b1a7605ade431e062f7a4c01a412f0b87543b6e995ad2a"
        }
      ]
    }
  ]
}

9.2 artifact-format

A security-related document in a specific format

Type: object

Table 89: Properties
Property Type Requirement Description
mediaType string Required

The Media Type of the document.

A media type shall appear at most once across the formats of a single TEA Artifact revision, so that every format can be selected unambiguously by media type when downloading its content or its signature.

description string Optional A free text describing the TEA Artifact
url string Optional

External download URL for this format of the TEA Artifact.

This is always a location outside the TEA API. When present, clients shall retrieve the content from it. When absent, the TEA server hosts the content itself and clients shall retrieve it from the artifact download endpoint, /artifact/{uuid}/{artifactVersion}/download, selecting this format by its mediaType.

url and signatureUrl should be stable URLs. Servers should not publish pre-signed or otherwise expiring URLs in them. A server that serves content from expiring storage links shall omit them and answer from the download endpoints, with 302 where the bytes live elsewhere.

A TEA access token is sent only to the TEA server's own API base URL, never to an external URL. External locations are either openly accessible or require credentials the client arranges separately.

External url values are part of the published artifact revision. Changing url shall create a new artifact revision, even when content bytes and checksums are unchanged. The server shall preserve the URLs published on each historical artifact revision. If a Collection adopts that new revision, collection versioning follows collection.version.

Byte stability for content retrieved through the server's download endpoint follows artifact.version.

The TEA server does not control the bytes behind an external url, so for every format that has a url the server shall publish at least one checksum: the checksums are the integrity statement for the revision. Content retrieved from url that does not match them is not the content of that revision.

Format: uri.

signatureUrl string Optional

External download URL for a detached signature of this format of the TEA Artifact.

As with url, this is always a location outside the TEA API. When present, clients shall retrieve the signature from it. When absent, clients shall retrieve it from the artifact signature download endpoint, /artifact/{uuid}/{artifactVersion}/signature/download, selecting this format by its mediaType; that endpoint returns 404 when no signature is published for the format. The same access-token, stable-URL, and revision rules as for url apply to signatureUrl. Byte stability for signature retrieval through the server's signature download endpoint follows artifact.version.

This specification does not define which signature technology is used, nor model the signing algorithm, key, or certificate chain.

Format: uri.

checksums Array of checksum Optional

Checksums for this artifact format's content bytes (the payload retrieved from url or from the artifact download endpoint for this mediaType), not the detached signature. When present, checksums shall contain at least one entry. When url is present, checksums is required. Those checksums are the integrity statement for that external url. Content retrieved from url that does not match them is not the content of that revision.

Published checksums shall be calculated over the artifact format's bytes before HTTP content coding is applied. Clients verifying them shall first remove any HTTP transfer coding and content coding, and shall not otherwise transform or canonicalize the artifact bytes. An artifact that is itself compressed, such as a .gz file, stays in that form. The TEA servers shall not declare the artifact's own compression as HTTP content coding, because clients would then remove it and the checksum would not match.

9.3 artifact-type

Type of TEA Artifact.

Type: string

Table 90: Enumeration of possible values
Value
ATTESTATION
BOM
BUILD_META
CERTIFICATION
FORMULATION
LICENSE
RELEASE_NOTES
SECURITY_TXT
THREAT_MODEL
VULNERABILITIES
OTHER

9.4 checksum

Integrity digest for identified content bytes. algValue is the lowercase hexadecimal encoding of the digest produced by algType over those bytes. The hex length shall match the algorithm's digest size (for example 40 for SHA-1, 64 for SHA-256 / SHA3-256 / BLAKE2b-256 / BLAKE3, 96 for SHA-384 / SHA3-384 / BLAKE2b-384, 128 for SHA-512 / SHA3-512 / BLAKE2b-512).

Type: object

Table 91: Properties
Property Type Requirement Description
algType checksum-type Required Checksum algorithm
algValue string Required Lowercase hexadecimal digest value for algType. Do not use Base64 or uppercase hex.
Minimum length: 40. Maximum length: 128. Pattern: ^[0-9a-f]+$.

9.5 checksum-type

Checksum algorithm

Type: string

Table 92: Enumeration of possible values
Value
SHA-1
SHA-256
SHA-384
SHA-512
SHA3-256
SHA3-384
SHA3-512
BLAKE2b-256
BLAKE2b-384
BLAKE2b-512
BLAKE3

9.6 cle

Lifecycle events for the object this endpoint is called on, as a TEA projection of the Common Lifecycle Enumeration (ECMA-428, 1st edition).

This is not a CLE document. The document envelope ($schema, identifier, updatedAt, and index / next page chaining) is not carried: the TEA object the response belongs to supplies the identity, and TEA has its own pagination. The event vocabulary, ordering and semantics are those of ECMA-428; the field shapes are TEA's. A consumer that needs a CLE document applies the mapping rules below and adds the envelope; a producer that holds a CLE document applies them in reverse. Publishers that need a bit-identical CLE 1.0.0 document publish it as a TEA Artifact in a release collection, as artifact type OTHER until a dedicated type exists; the same artifact may be referenced from more than one collection. The CLE endpoints are not a substitute for that document.

Mapping to ECMA-428:

  • identifiers[] on componentRenamed uses the TEA identifier shape (idType, idValue); CLE uses type / value with the same meaning.
  • A version specifier { version } names one version without a vers scheme, because a TEA server does not always know the package ecosystem. It corresponds to the CLE range vers:<scheme>/<version> once the scheme is known. { range } is a CLE range as-is.
  • cle-event is one flat object. The fields ECMA-428 requires or permits for each event type apply as written there; servers shall populate the required ones and omit fields that do not belong to the type.

Selection. Servers shall return in events a subset of the events of the CLE data they hold for the component or product, and shall not alter an event beyond the mapping above. On a release endpoint, servers may omit events scoped to other versions: events whose versions do not cover the release's version, and released events whose version differs from it. Events that name no version, other than withdrawn events, apply to the component as a whole and are retained. Inclusion of withdrawn events follows the rule below. Servers shall not otherwise reduce the set, and in particular shall not collapse it to the latest event per type. Servers shall not renumber event id values. Servers shall include a withdrawn event if, and only if, they include the event it withdraws. definitions.support shall contain at least the policies referenced by the included events.

events shall be ordered by id descending, as in ECMA-428. A server that provides CLE for an object answers 200, with an empty events array when no event has been recorded yet. A server that does not provide CLE for the object answers 404 with error: NOT_IMPLEMENTED; error: OBJECT_UNKNOWN means the object itself is unknown.

Type: object

Table 93: Properties
Property Type Requirement Description
events Array of cle-event Required Array of CLE Event objects representing lifecycle events. Events shall be ordered by id descending (newest events with highest IDs first).
definitions cle-definitions Optional Container for reusable policy definitions referenced by events
Example (Informative)
{
  "events": [
    {
      "id": 3,
      "type": "endOfSupport",
      "effective": "2025-06-01T00:00:00Z",
      "versions": [
        {
          "range": "vers:npm/>=1.0.0|<2.0.0"
        }
      ],
      "supportId": "standard",
      "published": "2025-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "type": "endOfDevelopment",
      "effective": "2025-01-01T00:00:00Z",
      "versions": [
        {
          "version": "1.0.0"
        }
      ],
      "supportId": "standard",
      "published": "2024-06-01T00:00:00Z"
    },
    {
      "id": 1,
      "type": "released",
      "effective": "2024-01-01T00:00:00Z",
      "version": "1.0.0",
      "license": "Apache-2.0",
      "published": "2024-01-01T00:00:00Z"
    }
  ],
  "definitions": {
    "support": [
      {
        "id": "standard",
        "description": "Standard product support policy",
        "url": "https://example.com/support/standard"
      }
    ]
  }
}

9.7 cle-definitions

Container for reusable CLE policy definitions

Type: object

Table 94: Properties
Property Type Requirement Description
support Array of cle-support-definition Optional List of support policies

9.8 cle-event

A discrete lifecycle event from the CLE specification (ECMA-428).

CLE timestamps in TEA responses use the shared date-time schema: UTC with the Z designator, fractional seconds preserved. A +00:00 offset in an upstream CLE document denotes the same instant and is re-expressed as Z. Any other offset is not UTC and is not valid CLE.

Type: object

Table 95: Properties
Property Type Requirement Description
id integer Required A unique, auto-incrementing integer identifier for the event
type cle-event-type Required The type of lifecycle event
effective date-time Required When the event takes effect.
published date-time Required When the event was first published.
version string Optional Version string (used by released event type)
versions Array of cle-version-specifier Optional List of version specifiers affected by this event
supportId string Optional Reference to a support policy ID defined in the definitions section
license string Optional License identifier (used by released event type)
supersededByVersion string Optional Version string that supersedes the affected versions (used by supersededBy event type)
identifiers Array of identifier Optional New identifiers for the component (componentRenamed only), in the TEA identifier shape. Corresponds to CLE identifiers[] with type / value.
eventId integer Optional ID of the event being withdrawn (used by withdrawn event type)
reason string Optional Human-readable explanation (used by withdrawn event type)
description string Optional Human-readable description of the event
references Array of string Optional List of URLs to supporting documentation
Example 1 (Informative)
{
  "id": 1,
  "type": "released",
  "effective": "2024-01-01T00:00:00Z",
  "version": "1.0.0",
  "license": "MIT",
  "published": "2023-06-01T00:00:00Z"
}
Example 2 (Informative)
{
  "id": 3,
  "type": "endOfSupport",
  "effective": "2024-01-01T00:00:00Z",
  "versions": [
    {
      "version": "1.0.0"
    }
  ],
  "supportId": "standard",
  "published": "2023-06-01T00:00:00Z"
}

9.9 cle-event-type

The type of CLE lifecycle event

Type: string

Table 96: Enumeration of possible values
Value
released
endOfDevelopment
endOfSupport
endOfLife
endOfDistribution
endOfMarketing
supersededBy
componentRenamed
withdrawn

9.10 cle-support-definition

A support policy definition from CLE

Type: object

Table 97: Properties
Property Type Requirement Description
id string Required Unique identifier for the support policy
description string Required Human-readable description of the policy
url string Optional URL to detailed documentation about this support policy
Format: uri.
Example (Informative)
{
  "id": "standard",
  "description": "Standard product support policy",
  "url": "https://example.com/support/standard"
}

9.11 cle-version-specifier

Which versions an event affects. Exactly one of version or range. range is an ECMA-428 version specification (vers). version names a single version without a vers scheme and is a TEA extension: it maps to vers:<scheme>/<version> when the ecosystem is known.

Type: object

Table 98: Properties
Property Type Requirement Description
version string Optional A specific version string
range string Optional A version range in vers format (e.g. "vers:npm/>=1.0.0|<2.0.0")

9.12 collection

A collection of security-related documents.

Every component release and product release has a collection. If no artifacts have been published when the release first becomes retrievable, the server serves version 1 with an empty artifacts list and updateReason.type: INITIAL_RELEASE. That version is immutable like any other; the first artifacts are published as version 2.

Type: object

Table 99: Properties
Property Type Requirement Description
uuid uuid Required UUID of the TEA Collection object. A TEA Collection shall use the same UUID as its parent Product Release or Component Release. Within an API base, a Product Release and a Component Release shall not share a UUID. Consequently, Collections belonging to different parent releases have different UUIDs. Versions of the same Collection retain the same UUID. See doc/tea-uuid-scope.md.
version integer Required TEA Collection version, incremented by 1 each time its content changes. Versions start with 1. Content changes include replacing an embedded artifact with a newer revision (for example one published because an external url or signatureUrl changed). If a Collection adopts that new artifact revision, the server shall publish a new Collection version. Previously published Collection versions shall remain unchanged. Classification of that adoption follows collection-update-reason-type.
createdDate date-time Required The date when the TEA Collection version was created.
belongsTo collection-belongs-to-type Required Indicates whether this collection belongs to a Component Release or a Product Release
updateReason collection-update-reason Required Reason for the update/release of the TEA Collection object.
artifacts Array of artifact Required Array of TEA Artifact objects (may be empty).
Example (Informative)
{
  "uuid": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab",
  "version": 10,
  "createdDate": "2024-12-15T00:00:00.000Z",
  "belongsTo": "COMPONENT_RELEASE",
  "updateReason": {
    "type": "VEX_UPDATED",
    "comment": "VDR file updated"
  },
  "artifacts": [
    {
      "uuid": "1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce",
      "createdDate": "2024-12-13T00:00:00.000Z",
      "version": 2,
      "name": "Build SBOM",
      "type": "BOM",
      "formats": [
        {
          "mediaType": "application/vnd.cyclonedx+xml",
          "description": "CycloneDX SBOM (XML)",
          "url": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml",
          "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml.asc",
          "checksums": [
            {
              "algType": "SHA-256",
              "algValue": "e04c9d55986d7194822eaa4f8115a77f801844d807ad6e0d454ac31dd41861e5"
            },
            {
              "algType": "SHA-1",
              "algValue": "5a7d4caef63c5c5ccdf07c39337323529eb5a770"
            }
          ]
        }
      ]
    },
    {
      "uuid": "dfa35519-9734-4259-bba1-3e825cf4be06",
      "createdDate": "2024-12-15T00:00:00.000Z",
      "version": 7,
      "name": "Vulnerability Disclosure Report",
      "type": "VULNERABILITIES",
      "formats": [
        {
          "mediaType": "application/vnd.cyclonedx+xml",
          "description": "CycloneDX VDR (XML)",
          "url": "https://logging.apache.org/cyclonedx/vdr.xml",
          "checksums": [
            {
              "algType": "SHA-256",
              "algValue": "75b81020b3917cb682b1a7605ade431e062f7a4c01a412f0b87543b6e995ad2a"
            }
          ]
        }
      ]
    }
  ]
}

9.13 collection-belongs-to-type

Indicates whether a collection belongs to a component release or a product release

Type: string

Table 100: Enumeration of possible values
Value
COMPONENT_RELEASE
PRODUCT_RELEASE

9.14 collection-update-reason

Reason for the update to the TEA collection

Type: object

Table 101: Properties
Property Type Requirement Description
type collection-update-reason-type Required Type of update reason.
comment string Optional Free text description

9.15 collection-update-reason-type

Type of TEA collection update.

VEX_UPDATED covers adding or revising an artifact of type VULNERABILITIES, including a revision whose external url or signatureUrl changed. VEX and VDR share that type. ARTIFACT_UPDATED covers a new revision of an artifact whose type is not VULNERABILITIES, including a revision whose external url or signatureUrl changed. Replacing an embedded artifact revision solely because its published url or signatureUrl changed is VEX_UPDATED when the artifact type is VULNERABILITIES, and ARTIFACT_UPDATED otherwise. Removing an artifact, including one of type VULNERABILITIES, counts as ARTIFACT_REMOVED.

The first Collection version shall use INITIAL_RELEASE. In subsequent versions, adding or revising an artifact of type VULNERABILITIES counts as VEX_UPDATED. When multiple change kinds occur, the server shall select updateReason.type using the precedence rule below.

When a collection version other than the first contains changes of more than one kind, the server shall set updateReason.type to the first applicable value in this order: VEX_UPDATED, ARTIFACT_REMOVED, ARTIFACT_ADDED, ARTIFACT_UPDATED. comment can describe the other changes. A client that needs the complete set of changes should compare the version with the previous one.

Type: string

Table 102: Enumeration of possible values
Value
INITIAL_RELEASE
VEX_UPDATED
ARTIFACT_UPDATED
ARTIFACT_ADDED
ARTIFACT_REMOVED

9.16 compliance-document-type

Well-known compliance document types. When idType is COMPLIANCE_DOCUMENT, the idValue shall be one of these values.

Type: string

Table 103: Enumeration of possible values
Value
SOC_2_TYPE_I
SOC_2_TYPE_II
SOC_3
ISO_27001
ISO_27017
ISO_27018
ISO_27701
ISO_42001
PCI_DSS
HIPAA
FEDRAMP
GDPR
CSA_STAR
NIST_800_53
NIST_800_171
CMMC
HITRUST
TISAX
CYBER_ESSENTIALS
CYBER_ESSENTIALS_PLUS
EU_DECLARATION_OF_CONFORMITY

9.17 component

A TEA component

Type: object

Table 104: Properties
Property Type Requirement Description
uuid uuid Required A unique identifier for the TEA component
name string Required Component name. Within a TEA server, component names should be unique among components. Uniqueness is an implementation recommendation, not a hard API requirement. Product and component names are separate namespaces; a product and a component may share the same name.
identifiers Array of identifier Required List of identifiers for the component
Example 1 (Informative)
{
  "uuid": "3910e0fd-aff4-48d6-b75f-8bf6b84687f0",
  "name": "Apache Log4j API",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-api"
    }
  ]
}
Example 2 (Informative)
{
  "uuid": "b844c9bd-55d6-478c-af59-954a932b6ad3",
  "name": "Apache Log4j Core",
  "identifiers": [
    {
      "idType": "CPE",
      "idValue": "cpe:2.3:a:apache:log4j"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core"
    }
  ]
}
Example 3 (Informative)
{
  "uuid": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "name": "Apache Tomcat",
  "identifiers": [
    {
      "idType": "CPE",
      "idValue": "cpe:2.3:a:apache:tomcat"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat"
    }
  ]
}

9.18 component-ref

A reference to a TEA component or specific component release

Type: object

Table 105: Properties
Property Type Requirement Description
uuid uuid Required A unique identifier for the TEA component
release uuid Optional Optional UUID of a specific release included in the product in the case where the product always include a specific release of a component. The product name should include a version identifier in this case.

9.19 component-release

A TEA Component Release

Type: object

Table 106: Properties
Property Type Requirement Description
uuid uuid Required A unique identifier of the TEA Component Release. Within an API base it shall not also identify a Product Release; see doc/tea-uuid-scope.md.
component uuid Required UUID of the TEA Component this release belongs to
componentName string Optional Name of the TEA Component this release belongs to
version string Required Human-readable version string
createdDate date-time Required Timestamp when this Release was created in TEA (for sorting purposes)
releaseDate date-time Optional Timestamp of the release
preRelease boolean Optional A flag indicating pre-release (or beta) status. May be disabled after the creation of the release object, but can't be enabled after creation of an object.
identifiers Array of identifier Optional Array of identifiers for the component release
distributions Array of release-distribution Optional List of different formats of this component release
Example 1 (Informative)
{
  "uuid": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab",
  "version": "2.24.3",
  "component": "b844c9bd-55d6-478c-af59-954a932b6ad3",
  "componentName": "Apache Log4j Core",
  "createdDate": "2024-12-10T10:51:00.000Z",
  "releaseDate": "2024-12-13T12:52:29.000Z",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core@2.24.3"
    }
  ]
}
Example 2 (Informative)
{
  "uuid": "605d0ecb-1057-40e4-9abf-c400b10f0345",
  "version": "11.0.7",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2025-05-07T18:08:00.000Z",
  "releaseDate": "2025-05-12T18:08:00.000Z",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7"
    }
  ],
  "distributions": [
    {
      "distributionId": "6a0d58e1-4896-4f1e-83f7-5feb6c032537",
      "description": "Core binary distribution, zip archive",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?type=zip"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.zip",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.zip.asc"
    },
    {
      "distributionId": "dba01c13-dd96-4928-be72-9c87ffa8cab8",
      "description": "Core binary distribution, tar.gz archive",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?type=tar.gz"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "2fcece641c62ba1f28e1d7b257493151fc44f161fb391015ee6a95fa71632fb9"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.tar.gz",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.tar.gz.asc"
    },
    {
      "distributionId": "cfe068c2-fae7-43d0-97ec-5ea092454040",
      "description": "Core binary distribution, Windows x64 zip archive",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?classifier=windows-x64&type=zip"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "62a5c358d87a8ef21d7ec1b3b63c9bbb577453dda9c00cbb522b16cee6c23fc4"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-windows-x64.zip",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-windows-x64.zip.asc"
    },
    {
      "distributionId": "de45ffaf-e4b5-47b5-be28-444a76df098e",
      "description": "Core binary distribution, Windows Service Installer (.exe)",
      "checksums": [
        {
          "algType": "SHA-512",
          "algValue": "1d3824e7643c8aba455ab0bd9e67b14a60f2aaa6aa7775116bce40eb0579e8ced162a4f828051d3b867e96ee2858ec5da0cc654e83a83ba30823cbea0df4ff96"
        }
      ],
      "url": "https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe",
      "signatureUrl": "https://downloads.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe.asc"
    }
  ]
}
Example 3 (Informative)
{
  "uuid": "95f481df-f760-47f4-b2f2-f8b76d858450",
  "version": "11.0.0-M26",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2024-09-13T17:49:00.000Z",
  "preRelease": true,
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.0-M26"
    }
  ]
}

9.20 component-release-with-collection

A TEA Component Release together with its latest collection.

Extends component-release with a latestCollection property; every field of component-release applies unchanged.

Includes all properties of component-release.

Table 107: Properties
Property Type Requirement Description
latestCollection collection Required The latest TEA Collection for this component release
Example (Informative)
{
  "uuid": "605d0ecb-1057-40e4-9abf-c400b10f0345",
  "version": "11.0.7",
  "createdDate": "2025-05-07T18:08:00.000Z",
  "releaseDate": "2025-05-12T18:08:00.000Z",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7"
    }
  ],
  "latestCollection": {
    "uuid": "605d0ecb-1057-40e4-9abf-c400b10f0345",
    "version": 2,
    "createdDate": "2025-05-12T18:08:00.000Z",
    "belongsTo": "COMPONENT_RELEASE",
    "updateReason": {
      "type": "VEX_UPDATED",
      "comment": "First artifacts published for this release"
    },
    "artifacts": [
      {
        "uuid": "3c8f5d2a-6b1e-4f7a-9c0d-2e5b8a1f4c93",
        "name": "Build SBOM",
        "version": 1,
        "createdDate": "2025-05-07T18:08:00.000Z",
        "type": "BOM",
        "formats": [
          {
            "mediaType": "application/vnd.cyclonedx+xml",
            "description": "CycloneDX SBOM (XML)",
            "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-cyclonedx.xml",
            "checksums": [
              {
                "algType": "SHA-256",
                "algValue": "66218c5c43e1a62fc2e3904500980241698aeddea4a6c446fda781c900e9d497"
              }
            ]
          }
        ]
      },
      {
        "uuid": "b7e2c4d9-1f3a-4a6e-8d5b-9c0e7f2a3b14",
        "name": "Vulnerability Disclosure Report",
        "version": 1,
        "createdDate": "2025-05-09T18:08:00.000Z",
        "type": "VULNERABILITIES",
        "formats": [
          {
            "mediaType": "application/vnd.cyclonedx+xml",
            "description": "CycloneDX VDR (XML)",
            "url": "https://tomcat.apache.org/cyclonedx/vdr.xml",
            "checksums": [
              {
                "algType": "SHA-256",
                "algValue": "3d93f05e799f6897570537313e8217dd67583c3b65f08ff0ebbce455357a6101"
              }
            ]
          }
        ]
      }
    ]
  }
}

9.21 date-time

Timestamp, RFC 3339 in UTC with the Z designator. Offsets are not accepted; servers shall convert to UTC before emitting. Fractional seconds are optional and preserved as sent. All timestamps in this specification use this schema.

Type: string

Format: date-time

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$

Example (Informative)
2024-03-20T15:30:00Z

9.22 discovery-info

Discovery information for one product release matched by a TEI or PURL lookup. A successful /discovery response is a non-empty array of these objects, ordered by priority when more than one release matches (first entry highest). .well-known/tea selects where /discovery is called; servers[] lists API bases that serve this product release (same version and priority selection rules). A rootUrl need not appear in the well-known endpoint list.

Type: object

Table 108: Properties
Property Type Requirement Description
productReleaseUuid uuid Required UUID of the resolved TEA Product Release
servers Array of server-info Required Non-empty array of TEA servers that serve this product release. Each entry has rootUrl (without trailing slash) and versions.

9.23 error-response

TEA API error body. Servers shall emit exactly this shape: error is one of the values of unknown-error-type, and message is the only other property allowed. Clients recognize a TEA error by an application/json response whose body is a JSON object with a string error property. Other JSON 404 bodies are not TEA error responses.

Any 4xx from a resource endpoint may carry an error-response body; when present, error is from unknown-error-type. Clients shall not require a body.

Type: object

Table 109: Properties
Property Type Requirement Description
error unknown-error-type Required
message string Optional Optional human-readable explanation for diagnostics. Clients shall not interpret it programmatically.

9.24 identifier

An identifier of a TEA object with a specified type. COMPLIANCE_DOCUMENT is valid only on TEA Components and TEA Component Releases (see identifier-type).

Type: object

Table 110: Properties
Property Type Requirement Description
idType identifier-type Required Type of identifier, e.g. TEI, PURL, CPE
idValue string Required Identifier value

9.25 identifier-type

Enumeration of identifier types.

COMPLIANCE_DOCUMENT marks a TEA Component or TEA Component Release as carrying a compliance document (for example a SOC 2 report), so that it can be discovered with idType=COMPLIANCE_DOCUMENT on /components and /componentReleases; the document itself is published as a TEA Artifact of the component release. It shall not be used on products, product releases, distributions, or CLE events.

Type: string

Table 111: Enumeration of possible values
Value
CPE
TEI
PURL
COMPLIANCE_DOCUMENT

9.26 paginated-collection-response

A paginated response containing TEA Collections

Includes all properties of pagination-details.

Table 112: Properties
Property Type Requirement Description
results Array of collection Required
Example 1 (Informative)
{
  "hasNext": true,
  "nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0",
  "results": []
}
Example 2 (Informative)
{
  "hasNext": false,
  "results": []
}

9.27 paginated-component-release-response

A paginated response containing TEA Component Releases

Includes all properties of pagination-details.

Table 113: Properties
Property Type Requirement Description
results Array of component-release Required
Example 1 (Informative)
{
  "hasNext": true,
  "nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0",
  "results": []
}
Example 2 (Informative)
{
  "hasNext": false,
  "results": []
}

9.28 paginated-component-response

A paginated response containing TEA Components

Includes all properties of pagination-details.

Table 114: Properties
Property Type Requirement Description
results Array of component Required
Example 1 (Informative)
{
  "hasNext": true,
  "nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0",
  "results": []
}
Example 2 (Informative)
{
  "hasNext": false,
  "results": []
}

9.29 paginated-product-release-response

A paginated response containing TEA Product Releases

Includes all properties of pagination-details.

Table 115: Properties
Property Type Requirement Description
results Array of product-release Required
Example 1 (Informative)
{
  "hasNext": true,
  "nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0",
  "results": []
}
Example 2 (Informative)
{
  "hasNext": false,
  "results": []
}

9.30 paginated-product-response

A paginated response containing TEA Products

Includes all properties of pagination-details.

Table 116: Properties
Property Type Requirement Description
results Array of product Required
Example 1 (Informative)
{
  "hasNext": true,
  "nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0",
  "results": []
}
Example 2 (Informative)
{
  "hasNext": false,
  "results": []
}

9.31 pagination-details

Type: object

Table 117: Properties
Property Type Requirement Description
hasNext boolean Required

A flag indicating whether there is another page of results to fetch.

When hasNext is true, nextPageToken shall be present. When hasNext is false, nextPageToken shall not be included.

Default: false.

nextPageToken string Optional

An opaque token that can be used in a following request to retrieve the next page of results.

This field shall be present when hasNext is true. This field shall not be included when hasNext is false.

Example 1 (Informative)
{
  "hasNext": true,
  "nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0"
}
Example 2 (Informative)
{
  "hasNext": false
}

9.32 product

A TEA product

Type: object

Table 118: Properties
Property Type Requirement Description
uuid uuid Required A unique identifier for the TEA product
name string Required Product name. Within a TEA server, product names should be unique among products. Uniqueness is an implementation recommendation, not a hard API requirement. Product and component names are separate namespaces; a product and a component may share the same name.
identifiers Array of identifier Required List of identifiers for the product, like TEI, CPE, PURL or other identifiers
Example (Informative)
{
  "uuid": "09e8c73b-ac45-4475-acac-33e6a7314e6d",
  "name": "Apache Log4j 2",
  "identifiers": [
    {
      "idType": "CPE",
      "idValue": "cpe:2.3:a:apache:log4j"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-api"
    }
  ]
}

9.33 product-release

A specific release of a TEA product

Type: object

Table 119: Properties
Property Type Requirement Description
uuid uuid Required A unique identifier for the TEA Product Release. Within an API base it shall not also identify a Component Release; see doc/tea-uuid-scope.md.
product uuid Required UUID of the TEA Product this release belongs to
productName string Optional Name of the TEA Product this release belongs to
version string Required Human-readable version string of the product release
createdDate date-time Required Timestamp when this Product Release was created in TEA (for sorting purposes)
releaseDate date-time Optional Timestamp of the product release
preRelease boolean Optional A flag indicating pre-release (or beta) status. May be disabled after the creation of the release object, but can't be enabled after creation of an object.
identifiers Array of identifier Optional Array of identifiers for the product release (idType is CPE, TEI or PURL; COMPLIANCE_DOCUMENT is not valid here)
components Array of component-ref Required Array of component references that compose this product release. A component reference can optionally include the UUID of a specific component release to pin the exact version.
Example (Informative)
{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "version": "2.24.3",
  "product": "09e8c73b-ac45-4475-acac-33e6a7314e6d",
  "createdDate": "2025-04-01T15:43:00.000Z",
  "releaseDate": "2025-04-01T15:43:00.000Z",
  "identifiers": [
    {
      "idType": "TEI",
      "idValue": "tei://vendor.example.com/uuid/47f51950-b0e2-11f1-adc2-1a52914d44b2"
    }
  ],
  "components": [
    {
      "uuid": "3910e0fd-aff4-48d6-b75f-8bf6b84687f0"
    },
    {
      "uuid": "b844c9bd-55d6-478c-af59-954a932b6ad3",
      "release": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab"
    }
  ]
}

9.34 product-release-with-collection

A TEA Product Release together with its latest collection.

Extends product-release with a latestCollection property; every field of product-release applies unchanged.

Includes all properties of product-release.

Table 120: Properties
Property Type Requirement Description
latestCollection collection Required The latest TEA Collection for this product release
Example (Informative)
{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "version": "2.24.3",
  "product": "09e8c73b-ac45-4475-acac-33e6a7314e6d",
  "createdDate": "2025-04-01T15:43:00.000Z",
  "releaseDate": "2025-04-01T15:43:00.000Z",
  "identifiers": [
    {
      "idType": "TEI",
      "idValue": "tei://vendor.example.com/uuid/47f51950-b0e2-11f1-adc2-1a52914d44b2"
    }
  ],
  "components": [
    {
      "uuid": "3910e0fd-aff4-48d6-b75f-8bf6b84687f0"
    },
    {
      "uuid": "b844c9bd-55d6-478c-af59-954a932b6ad3",
      "release": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab"
    }
  ],
  "latestCollection": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "version": 1,
    "createdDate": "2025-04-01T15:43:00.000Z",
    "belongsTo": "PRODUCT_RELEASE",
    "updateReason": {
      "type": "INITIAL_RELEASE"
    },
    "artifacts": []
  }
}

9.35 release-distribution

Type: object

Table 121: Properties
Property Type Requirement Description
distributionId uuid Required A unique identifier for the TEA Distribution object (uuid)
description string Optional Free-text description of the distribution
identifiers Array of identifier Optional Array of identifiers specific to this distribution
url string Optional Direct download URL for the distribution. This is always a location outside the TEA API. A TEA access token is sent only to the TEA server's own API base URL, never to an external URL: distribution locations are either openly accessible, pre-signed, or require credentials the client arranges separately.
Format: uri.
signatureUrl string Optional Direct download URL for the distribution's external signature. As with url, this is always a location outside the TEA API. A TEA access token is sent only to the TEA server's own API base URL, never to an external URL.
Format: uri.
checksums Array of checksum Optional Array of checksums for the distribution payload retrieved from url (the distribution bytes, not the signature at signatureUrl).
Example 1 (Informative)
{
  "distributionId": "6a0d58e1-4896-4f1e-83f7-5feb6c032537",
  "description": "Core binary distribution, zip archive",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?type=zip"
    }
  ],
  "checksums": [
    {
      "algType": "SHA-256",
      "algValue": "9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1"
    }
  ],
  "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.zip",
  "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.zip.asc"
}
Example 2 (Informative)
{
  "distributionId": "dba01c13-dd96-4928-be72-9c87ffa8cab8",
  "description": "Core binary distribution, tar.gz archive",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?type=tar.gz"
    }
  ],
  "checksums": [
    {
      "algType": "SHA-256",
      "algValue": "2fcece641c62ba1f28e1d7b257493151fc44f161fb391015ee6a95fa71632fb9"
    }
  ],
  "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.tar.gz",
  "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.tar.gz.asc"
}
Example 3 (Informative)
{
  "distributionId": "cfe068c2-fae7-43d0-97ec-5ea092454040",
  "description": "Core binary distribution, Windows x64 zip archive",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?classifier=windows-x64&type=zip"
    }
  ],
  "checksums": [
    {
      "algType": "SHA-256",
      "algValue": "62a5c358d87a8ef21d7ec1b3b63c9bbb577453dda9c00cbb522b16cee6c23fc4"
    }
  ],
  "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-windows-x64.zip",
  "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-windows-x64.zip.asc"
}
Example 4 (Informative)
{
  "distributionId": "de45ffaf-e4b5-47b5-be28-444a76df098e",
  "description": "Core binary distribution, Windows Service Installer (.exe)",
  "checksums": [
    {
      "algType": "SHA-512",
      "algValue": "1d3824e7643c8aba455ab0bd9e67b14a60f2aaa6aa7775116bce40eb0579e8ced162a4f828051d3b867e96ee2858ec5da0cc654e83a83ba30823cbea0df4ff96"
    }
  ],
  "url": "https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe",
  "signatureUrl": "https://downloads.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe.asc"
}

9.36 server-info

TEA server information including URL, versions, and optional priority

Type: object

Table 122: Properties
Property Type Requirement Description
rootUrl string Required Absolute API base URL for this TEA server, without trailing slash. Shall not include userinfo, query, or fragment. The scheme match is lowercase only (normalized form). Conforming deployments use lowercase https; http is allowed only so local-test documents still validate.
Format: uri. Pattern: ^https?://[^/?#@]+(/[^?#\s]*[^/?#\s])?$.
versions Array of string Required Supported TEA API versions at this server, without a leading v. Each value is full SemVer 2.0.0 (MAJOR.MINOR.PATCH with optional prerelease and build metadata). Clients select the highest mutually supported version and append /v followed by that exact string.
priority number Optional Optional priority for this server (0.0 to 1.0, where 1.0 is highest priority). If omitted in the JSON response, clients shall treat the effective priority as 1.0 when ordering servers (the same rule as for .well-known/tea endpoint priority).
Default: 1. Minimum: 0. Maximum: 1. Format: float.

9.37 token-error-response

Token error response, as defined in RFC 6749 section 5.2.

Type: object

Table 123: Properties
Property Type Requirement Description
error string (enum) Required Error code as defined in RFC 6749 section 5.2.
One of: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope.
error_description string Optional Human-readable text providing additional information about the error.
error_uri string Optional URI of a human-readable web page with information about the error.
Format: uri.

9.38 token-request

Token request for the client_credentials grant, as defined in RFC 6749 section 4.4.2, or an optional assertion grant identified below. The scope parameter applies to both. The assertion parameter applies only to assertion grants. RFC 8693 token exchange is outside the TEA 1.0 profile (see /token description).

Type: object

Table 124: Properties
Property Type Requirement Description
grant_type string Required OAuth 2.0 grant type. Servers shall support client_credentials. Servers may support assertion grants (urn:ietf:params:oauth:grant-type:saml2-bearer, urn:ietf:params:oauth:grant-type:jwt-bearer). Token exchange (urn:ietf:params:oauth:grant-type:token-exchange) is outside the TEA 1.0 interoperable authentication profile; see /token.
scope string Optional Optional space-delimited scope request (RFC 6749 section 3.3). TEA does not define scope values; servers may ignore this parameter.
assertion string Optional Assertion value, when an assertion grant type is used (RFC 7521 section 4.1).

9.39 token-response

Successful token response, as defined in RFC 6749 section 5.1.

Type: object

Table 125: Properties
Property Type Requirement Description
access_token string Required The issued access token, presented on other TEA endpoints as Authorization: Bearer <access_token>. Opaque to the client.
token_type string Required Token type. Always Bearer in TEA.
expires_in integer Optional Lifetime of the access token in seconds. Servers should include this so that clients can re-authenticate before expiry rather than on failure.
scope string Optional Granted scope, when it differs from the scope requested.

9.40 unknown-error-type

Classification of TEA error response

Type: string

Table 126: Enumeration of possible values
Value
OBJECT_UNKNOWN
NOT_IMPLEMENTED
NO_ACCEPTABLE_FORMAT
SIGNATURE_NOT_FOUND
INVALID_REQUEST
INVALID_PAGE_TOKEN

9.41 uuid

A UUID in lower case (RFC 9562)

Type: string

Format: uuid

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Annex A (normative) TEA well-known discovery schema

This annex specifies the schema for the TEA /.well-known/tea discovery document. The schema is expressed in JSON Schema draft-07 (draft-handrews-json-schema-01, draft-handrews-json-schema-validation-01).

The following JSON document is the schema. The tables that follow summarise it.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://cyclonedx.github.io/transparency-exchange-api/discovery/tea-well-known.schema.json",
  "title": "TEA .well-known discovery document",
  "description": "JSON Schema for the TEA .well-known/tea discovery payload that lists available TEA API endpoints and supported versions.",
  "type": "object",
  "additionalProperties": false,
  "required": ["schemaVersion", "endpoints"],
  "properties": {
    "schemaVersion": {
      "type": "integer",
      "const": 1,
      "description": "Schema version for the TEA .well-known discovery document. Currently always 1."
    },
    "endpoints": {
      "type": "array",
      "description": "List of available TEA service endpoints and their supported versions.",
      "minItems": 1,
      "items": { "$ref": "#/definitions/endpoint" }
    }
  },
  "definitions": {
    "endpoint": {
      "type": "object",
      "additionalProperties": false,
      "required": ["url", "versions"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "pattern": "^https?://[^/?#@]+(/[^?#\\s]*[^/?#\\s])?$",
          "description": "Absolute API base URL of the TEA endpoint, without trailing slash. Shall not include userinfo, query, or fragment. The scheme match is lowercase only (normalized form). Conforming deployments use lowercase https; http is allowed only so local-test documents still validate."
        },
        "versions": {
          "type": "array",
          "description": "Supported TEA API versions for this endpoint. Select the highest mutually supported version and append /v followed by that exact string (no leading v in array values).",
          "minItems": 1,
          "items": {
            "type": "string",
            "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
            "examples": [
              "1.0.0"
            ],
            "description": "TEA OpenAPI Spec version identifier as full SemVer 2.0.0 (MAJOR.MINOR.PATCH with optional prerelease and build metadata; https://semver.org/)."
          }
        },
        "priority": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 1,
          "description": "Optional priority for this endpoint. Higher values indicate higher priority. Range: 0 to 1. If omitted in the JSON response, clients shall treat the effective priority as 1 (JSON Schema default does not populate omitted fields)."
        }
      }
    }
  },
  "examples": [
    {
      "schemaVersion": 1,
      "endpoints": [
        {
          "url": "https://api.example.com",
          "versions": ["1.0.0"],
          "priority": 1
        },
        {
          "url": "https://api2.example.com/mytea",
          "versions": ["1.0.0"],
          "priority": 0.5
        }
      ]
    }
  ]
}

JSON Schema for the TEA .well-known/tea discovery payload that lists available TEA API endpoints and supported versions.

Type: object

Additional properties are not permitted.

Table 127: Properties
Property Type Requirement Description
schemaVersion integer Required Schema version for the TEA .well-known discovery document. Currently always 1.
Constant: 1.
endpoints Array of endpoint Required List of available TEA service endpoints and their supported versions.
Minimum items: 1.
Example (Informative)
{
  "schemaVersion": 1,
  "endpoints": [
    {
      "url": "https://api.example.com",
      "versions": [
        "1.0.0"
      ],
      "priority": 1
    },
    {
      "url": "https://api2.example.com/mytea",
      "versions": [
        "1.0.0"
      ],
      "priority": 0.5
    }
  ]
}

A.1 endpoint

Type: object

Additional properties are not permitted.

Table 128: Properties
Property Type Requirement Description
url string Required Absolute API base URL of the TEA endpoint, without trailing slash. Shall not include userinfo, query, or fragment. The scheme match is lowercase only (normalized form). Conforming deployments use lowercase https; http is allowed only so local-test documents still validate.
Format: uri. Pattern: ^https?://[^/?#@]+(/[^?#\s]*[^/?#\s])?$.
versions Array of string Required Supported TEA API versions for this endpoint. Select the highest mutually supported version and append /v followed by that exact string (no leading v in array values).
Minimum items: 1. Each item: TEA OpenAPI Spec version identifier as full SemVer 2.0.0 (MAJOR.MINOR.PATCH with optional prerelease and build metadata; https://semver.org/). Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. Examples: 1.0.0.
priority number Optional Optional priority for this endpoint. Higher values indicate higher priority. Range: 0 to 1. If omitted in the JSON response, clients shall treat the effective priority as 1 (JSON Schema default does not populate omitted fields).
Default: 1. Minimum: 0. Maximum: 1.

Annex B (informative) Specification narrative

The following sections are derived from the working group's authoring notes maintained as Markdown in the source repository.

B.1 Transparency Exchange API: Consumer access

The consumer access starts with a TEI, A Transparency Exchange Identifier. This is used to find the API server as described in the discovery document.

B.1.1 API usage

The standard TEI points to a product release. A product release is something sold, downloaded as an open source project or acquired by other means. It contains one or multiple component releases.

  • List of TEA Component Releases: Component releases are components of a product release. Each Component release has its own versioning and its own set of artefacts, they have a timestamp and a lifecycle enumeration. They are normally sorted by timestamps. The TEA API has no requirements of type of version string (semantic or any other scheme) - it's just an identifier set by the manufacturer.
  • List of TEA Collections: For each release, there is a list of TEA collections as indicated by release date and a version integer starting with collection version 1.
  • List of TEA Artifacts: The collection is unique for a version and contains a list of artefacts. This can be SBOM files, VEX, SCITT, IN-TOTO or other documents. Note that a single artefact can belong to multiple Component or Product Releases.
  • List of artefact formats: An artefact can be published in multiple formats.

Finding the list of artefacts for a Product Release starts from the product release TEI and, in some cases, the version of each component (TEA Component Release).

B.1.2 API flow based on TEI discovery

Figure 1
TEA Component ReleaseTEA Product ReleaseTEA Discovery / TEA ServerTEA Component ReleaseTEA Product ReleaseTEA Discovery / TEA Serveralt[Multiple Product Releases returned]loop[For each tea_component_release]ManufacturerTEA ClientProvides TEI (Transparency Exchange Identifier)1GET https://<domain>/.well-known/tea2TEA discovery document (API servers & endpoints)3Call Discovery endpoint with TEI4Product Release reference(s)5Resolve Product Release(s)6List of Component Releases7Identify Discriminating Component Releases8Resolve Discriminating Component Releases9Discriminating Component Release Details10Converge on a Single Product Release11Resolve Product Release Details12Product Release with its latest Collection and the list of Component Releases13Resolve Component Release Details14Component Release with its latest Collection (list of TEA Artifacts)15ManufacturerTEA ClientTEA consumer flow

B.1.3 API flow based on direct access to API

In this case, the client wants to search for a specific product release using the API

Figure 2
TEA ArtifactTEA CollectionTEA Component ReleaseTEA Product ReleaseTEA ArtifactTEA CollectionTEA Component ReleaseTEA Product ReleaseuserSearch for product releases based on identifier (CPE, PURL, TEI)1List of product releases2Finding all product parts (TEA Component Releases) and facts about chosen product3List of TEA Component Releases4Finding information of a component release5Component release with its latest Collection6Finding all TEA Artifacts for TEA Component Release7List of TEA Artifacts and formats available for each TEA Artifact8Request to download TEA artifact9TEA Artifact10userTEA client flow with search

B.1.4 API flow based on cached data - checking for a new release

In this case a TEA client knows the component UUID and wants to check the status of the used release and if there's a new release.

Figure 3
TEA Component ReleaseTEA ComponentTEA Component ReleaseTEA ComponentuserFinding a specific version/release1List of releases and collection id for each release2Details for discovered release3Collection with artefact details for the release4userTEA client flow with direct query for release

B.1.5 API flow based on cached data - checking if a collection changed

In this case a TEA client knows the release UUID, the collection UUID, and the collection version from previous queries. If the given version is not the same, another query is done to get reason for update and new collection list of artefacts.

Figure 4
TEA CollectionTEA CollectionuserFinding the current collection, including version1List of artefacts and formats available for each artefact2Request to access previous version of the collection to compare3Previous version of collection4userTEA client collection query

B.2 The TEA Product object

After TEA discovery, the Transparency Exchange Identifier (TEI) resolves to one or more TEA Product Releases, each a concrete, versioned offering; a TEI normally resolves to exactly one. A TEA Product is a higher-level object that groups multiple Product Releases for a product line or family and can be browsed via /product/{uuid}/releases.

  • A product release may consist of a single component, the output will be metadata about the product and the TEA COMPONENT object.
  • For a composed product release consisting of a bundle of components or component releases, the response will be multiple TEA COMPONENT objects.

In addition, all known TEIs for the product will be returned, in order for a TEA client to avoid duplication. This list can also include known Package URLs (PURL) and CPEs for the product.

B.2.1 Authorization

Authorization can be done on multiple levels, including which products and versions are supported for a specific user.

B.2.2 Composite products

A TEA Product Release will be the starting point of discovery. The TEA product release will list all included components with the UUID of the TEA component. The reference list may also include a UUID of a specific release of a component in the case where a product always includes a single release of the component.

The TEA Product object groups multiple releases together.

B.2.3 Structure

Key attributes:

  • uuid: A unique identifier for the TEA product
  • name: Product name
  • identifiers: List of identifiers for the product
    • idType: Type of identifier, e.g. TEI, PURL, CPE
    • idValue: Identifier value

Required fields:

  • uuid, name, identifiers

B.2.3.1 Example

An example of a product consisting of an OSS project and all its Maven artefacts:

{
  "uuid": "09e8c73b-ac45-4475-acac-33e6a7314e6d",
  "name": "Apache Log4j 2",
  "identifiers": [
    {
      "idType": "CPE",
      "idValue": "cpe:2.3:a:apache:log4j"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-api"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-layout-template-json"
    }
  ]
}

Releases for this Product can be browsed via the API endpoint /product/{uuid}/releases.

B.2.3.2 API usage

The user will find this API end point using TEA discovery.

A user will approach the API just to discover data before purchase, or with a specific product and product version in scope. The format of the version string can follow many syntaxes. This specification does not constrain that format.

An automated system may want to provide the user with a GUI, listing versions and being able to scroll to the next page until the user selects a version.

B.3 The TEA Product Release object

B.3.1 Overview

A TEA Product Release represents a specific versioned release of a TEA Product. It is the primary resolvable entity via TEI and the entry point for discovery of included components and related collections of security artefacts.

Key attributes:

  • uuid: A unique identifier for the TEA Product Release
  • product: UUID of the TEA Product this release belongs to
  • productName: Optional name of the parent product
  • version: Human-readable version string of the product release
  • createdDate: Timestamp when the product release was created in TEA (for sorting purposes)
  • releaseDate: Timestamp of the product release
  • preRelease: A flag indicating pre-release (or beta) status. May be disabled after the creation of the release object, but can't be enabled after creation of an object. (boolean)
  • identifiers: Array of identifiers for the product release (idType: CPE/TEI/PURL; idValue: string)
  • components: Array of component references that compose this product release. A component reference can optionally include the UUID of a specific component release to pin the exact version.

Required fields:

  • uuid, product, version, createdDate, components

Collections for a product release contain artefacts relevant to that product release.

B.3.2 JSON examples

The following example is reused from the OpenAPI schema (components/schemas/product-release.examples), ensuring exact field names and casing.

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "version": "2.24.3",
  "createdDate": "2025-04-01T15:43:00Z",
  "releaseDate": "2025-04-01T15:43:00Z",
  "product": "09e8c73b-ac45-4475-acac-33e6a7314e6d",
  "identifiers": [
    {
      "idType": "TEI",
      "idValue": "tei://vendor.example.com/uuid/47f51950-b0e2-11f1-adc2-1a52914d44b2"
    }
  ],
  "components": [
    {
      "uuid": "3910e0fd-aff4-48d6-b75f-8bf6b84687f0"
    },
    {
      "uuid": "b844c9bd-55d6-478c-af59-954a932b6ad3",
      "release": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab"
    }
  ]
}

B.3.3 Handling the Pre-Release flag

The "Pre-release" flag is used to indicate that this is not a final release. For a given product release with a UUID, the flag can be set to indicate a "test", "beta", "alpha" or similar non-deployed release. It can only be set when creating the product release. The TEA implementation may allow it to be unset (False) once. This is to support situations where a object is promoted as is after testing to production version. The flag can not be set after initial creation and publication of the product release.

If the final version is different from the pre-release (bugs fixed, code changed, different binary) a new product release with a new UUID and version shall be created.

B.3.4 Notes

  • Use uppercase idType values exactly as defined by the schema enum: CPE, TEI, PURL.

B.4 The TEA Component object

The TEA Component represents a component lineage. A product release may be constructed with one or multiple TEA Components, each with their own set of releases and related artefacts. The component has releases, which has a set of artifacts for each release. One artifact may belong to multiple releases.

Each TEA Component has a list of Component Releases (see /component/{uuid}/releases), which enumerates all known versions for that component.

The TEA API is agnostic as to how a "version" is indicated - semver, vers, name, hash or anything else.

B.4.1 Versions and TEIs

A TEI resolves to one or more Product Releases. A Product groups related Product Releases.

For the API to be able to present a list of versions in a chronological order, a timestamp for a release is required.

B.4.2 Structure

A TEA Component object has the following parts:

  • uuid: A unique identifier for the TEA component
  • name: Component name
  • identifiers: List of identifiers for the component
    • idType: Type of identifier, e.g. TEI, PURL, CPE
    • idValue: Identifier value

Required fields:

  • uuid, name, identifiers

B.4.2.1 Examples

Some examples of Maven artefacts as TEA Components:

{
  "uuid": "3910e0fd-aff4-48d6-b75f-8bf6b84687f0",
  "name": "Apache Log4j API",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-api"
    }
  ]
}
{
  "uuid": "b844c9bd-55d6-478c-af59-954a932b6ad3",
  "name": "Apache Log4j Core",
  "identifiers": [
    {
      "idType": "CPE",
      "idValue": "cpe:2.3:a:apache:log4j"
    },
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core"
    }
  ]
}

B.4.3 References

B.5 The TEA Component Release object

B.5.1 Overview

A TEA Component Release represents a specific version of a TEA Component lineage. It is the concrete, versioned entity which has collections of security-related artifacts (SBOM, VDR/VEX, attestations, etc.).

A TEA Component Release object represents a specific version of a component, identified by a unique version number and associated metadata. Each release may include multiple distributions, which capture variations such as architecture, packaging, or localization.

  • For software components, each distribution typically corresponds to a different digital file delivered to users (e.g., by platform or packaging type).
  • For hardware components, distributions may reflect differences in packaging, language, or other physical attributes.

Each distribution is assigned a distributionId, a UUID defined by the producer, which is used to associate relevant TEA Artifacts with that distribution. Since TEA Artifacts can be associated with multiple release objects, a distributionId is unique within the TEA server and is not reused for a different distribution, so the association stays reliable across releases. What a distribution represents for the producer is carried by its description, not by its identifier.

Key attributes:

  • uuid: Unique identifier of the TEA Component Release (uuid)
  • component: UUID of the TEA Component this release belongs to
  • componentName: Name of the TEA Component this release belongs to
  • version: Human-readable version string
  • createdDate: Timestamp when this Release was created in TEA (for sorting purposes)
  • releaseDate: Timestamp of the release
  • preRelease: A flag indicating pre-release (or beta) status. May be disabled after the creation of the release object, but can't be enabled after creation of an object.
  • identifiers: Array of identifiers for the component release
  • distributions: List of different formats of this component release

Collections for a release contain artifacts relevant to that specific release.

Required fields:

  • uuid, component, version, createdDate

B.5.2 The TEA Component Release Distribution object

Distribution are object to declare different distribution formats of a component, like source code or a package for a specific Linux distribution or a CPU type

Key attributes:

  • distributionId: A unique identifier for the TEA Distribution object (uuid)
  • description: Free-text description of the distribution.
  • identifiers: Array of identifiers for the distribution of the release
  • url: Direct download URL for the distribution
  • signatureUrl: Direct download URL for the distribution's detached signature
  • checksums: Array of checksums for the distribution
    • algType: Checksum algorithm used.
    • algValue: Checksum value.

Required fields:

  • distributionId

B.5.3 JSON examples

The following examples are reused from the OpenAPI schema (components/schemas/component-release.examples), ensuring exact field names and casing.

{
  "uuid": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab",
  "version": "2.24.3",
  "component": "b844c9bd-55d6-478c-af59-954a932b6ad3",
  "componentName": "Apache Log4j Core",
  "createdDate": "2024-12-10T10:51:00Z",
  "releaseDate": "2024-12-13T12:52:29Z",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core@2.24.3"
    }
  ]
}
{
  "uuid": "605d0ecb-1057-40e4-9abf-c400b10f0345",
  "version": "11.0.7",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2025-05-07T18:08:00Z",
  "releaseDate": "2025-05-12T18:08:00Z",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7"
    }
  ]
}
{
  "uuid": "95f481df-f760-47f4-b2f2-f8b76d858450",
  "version": "11.0.0-M26",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2024-09-13T17:49:00Z",
  "preRelease": true,
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.0-M26"
    }
  ]
}

B.5.3.1 Examples

B.5.3.1.1 Single distribution

This example shows a TEA Component Release for Apache Log4j Core, which is distributed as a single JAR file. Even though there is only one distribution, the distributions attribute is included to enable searching for the release by the SHA-256 checksum of the JAR. This structure also allows for future extensibility if additional distributions are introduced.

Example of simple release
{
  "uuid": "b1e2c3d4-5678-49ab-9cde-123456789abc",
  "version": "2.24.3",
  "component": "b844c9bd-55d6-478c-af59-954a932b6ad3",
  "createdDate": "2024-12-10T10:51:00Z",
  "releaseDate": "2024-12-13T12:52:29Z",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core@2.24.3"
    }
  ],
  "distributions": [
    {
      "distributionId": "0f3b9c51-2a4d-4a1e-9f6c-7d8e5b3a2c14",
      "description": "Binary distribution, JAR",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.logging.log4j/log4j-core@2.24.3?type=jar"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "b1e2c3d4f5a67890b1e2c3d4f5a67890b1e2c3d4f5a67890b1e2c3d4f5a67890"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3.jar",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3.jar.asc"
    }
  ]
}

B.5.3.1.2 Multiple distributions

This is an example of a TEA Component Release for Apache Tomcat 11.0.7 binary distributions. The example defines four distinct distributions, which is essential not only for associating the correct SBOMs with each distribution, but also for accurately tracking and reporting vulnerabilities that may affect only specific distributions. For instance:

  • The zip and tar.gz archives contain only Java JARs.
  • The Windows x64 zip archive additionally includes the Apache Procrun binary, which is specific to Windows and may introduce unique vulnerabilities.
  • The Windows Service Installer contains the same data as the Windows x64 zip archive, but is packaged as a self-extracting installer created by the Nullsoft Scriptable Install System.

By giving each of these its own distributionId, it becomes possible to precisely associate artefacts and vulnerability disclosures with the affected distributions, ensuring accurate risk assessment and remediation. The description of a distribution carries what it represents; the identifier itself is opaque.

Example of four different binary distributions in the same release
{
  "uuid": "605d0ecb-1057-40e4-9abf-c400b10f0345",
  "version": "11.0.7",
  "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
  "createdDate": "2025-05-07T18:08:00Z",
  "releaseDate": "2025-05-12T18:08:00Z",
  "identifiers": [
    {
      "idType": "PURL",
      "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7"
    }
  ],
  "distributions": [
    {
      "distributionId": "6a0d58e1-4896-4f1e-83f7-5feb6c032537",
      "description": "Core binary distribution, zip archive",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?type=zip"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.zip",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.zip.asc"
    },
    {
      "distributionId": "dba01c13-dd96-4928-be72-9c87ffa8cab8",
      "description": "Core binary distribution, tar.gz archive",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?type=tar.gz"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "2fcece641c62ba1f28e1d7b257493151fc44f161fb391015ee6a95fa71632fb9"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.tar.gz",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7.tar.gz.asc"
    },
    {
      "distributionId": "cfe068c2-fae7-43d0-97ec-5ea092454040",
      "description": "Core binary distribution, Windows x64 zip archive",
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.7?classifier=windows-x64&type=zip"
        }
      ],
      "checksums": [
        {
          "algType": "SHA-256",
          "algValue": "62a5c358d87a8ef21d7ec1b3b63c9bbb577453dda9c00cbb522b16cee6c23fc4"
        }
      ],
      "url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-windows-x64.zip",
      "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-windows-x64.zip.asc"
    },
    {
      "distributionId": "de45ffaf-e4b5-47b5-be28-444a76df098e",
      "description": "Core binary distribution, Windows Service Installer (.exe)",
      "checksums": [
        {
          "algType": "SHA-512",
          "algValue": "1d3824e7643c8aba455ab0bd9e67b14a60f2aaa6aa7775116bce40eb0579e8ced162a4f828051d3b867e96ee2858ec5da0cc654e83a83ba30823cbea0df4ff96"
        }
      ],
      "url": "https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe",
      "signatureUrl": "https://downloads.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe.asc"
    }
  ]
}

B.5.4 Handling the Pre-Release flag

B.5.4.1 Pre-release flag usage

The preRelease flag is used to indicate that a release is not production ready, regardless of the version naming scheme. This helps consumers identify non-production releases without relying on conventions like -beta, -rc, or -M in the version string.

There are two main scenarios for using the preRelease flag:

  • Pending release: The distribution is still undergoing quality assurance or review and is not yet officially released. These typically lack a releaseDate attribute. Once the release is approved, the preRelease flag is set to false and the releaseDate is added.
  • Permanent pre-release: The distribution is intentionally marked as a pre-release (e.g., beta, milestone, or release candidate) and will never be considered production ready, even after all checks are complete. These may have a releaseDate, but preRelease remains true.
Examples of non-production ready distributions
  • Pending release (no releaseDate):
    {
      "uuid": "e2a1c7b4-3f2d-4e8a-9c1a-7b2e4d5f6a8b",
      "version": "11.0.0",
      "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
      "createdDate": "2025-09-01T00:00:00Z",
      "preRelease": true,
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.0?repository_url=https:%2F%2Frepository.apache.org%2Fcontent%2Fgroups%2Fstaging%2F"
        }
      ]
    }
  • Transition to production-ready (preRelease flag turned off, releaseDate added):
    {
      "uuid": "e2a1c7b4-3f2d-4e8a-9c1a-7b2e4d5f6a8b",
      "version": "11.0.0",
      "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
      "createdDate": "2025-09-01T00:00:00Z",
      "releaseDate": "2025-09-10T12:00:00Z",
      "preRelease": false,
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.0"
        }
      ]
    }
  • Beta version (has releaseDate, but not production ready):
    {
      "uuid": "95f481df-f760-47f4-b2f2-f8b76d858450",
      "version": "11.0.0-M26",
      "component": "c71b316e-ae77-11f1-aafb-1a52914d44b2",
      "createdDate": "2024-09-13T17:49:00Z",
      "releaseDate": "2024-09-16T17:49:00Z",
      "preRelease": true,
      "identifiers": [
        {
          "idType": "PURL",
          "idValue": "pkg:maven/org.apache.tomcat/tomcat@11.0.0-M26"
        }
      ]
    }

Notes:

  • Use uppercase idType values exactly as defined by the schema enum: CPE, TEI, PURL.

B.6 The TEA Collection object

For each product and version there is a Tea Collection object (TCO), which is a list of available artifacts for this specific version.

The TEA collection is normally created by the TEA application server at publication time of artifacts. The publisher may sign the collection object as a JSON file at time of publication.

A release is never served without a collection. If no artifacts have been published when the release first becomes retrievable, the server serves collection version 1 with an empty artifacts list and updateReason.type: INITIAL_RELEASE. That version is immutable like any other; the first artifacts are published as version 2. Classification follows the update-reason rules below. A publisher that publishes the release and its artifacts together never has an empty version and starts at version 1 with content. In both cases version 1 is the first collection a client could have retrieved. A server may also synthesize the collection dynamically (see below).

If there are any updates of artefacts within a collection for the same version of a product, then a new TEA Collection object is created and optionally signed. This update will have the same UUID, but a new version number. A reason for the update will have to be provided. This shall be used to correct mistakes, spelling errors as well as to provide new information on dynamic artifact types such as CLE or VEX. If the product is modified, that is a new product version and that should generate a new collection object with a new UUID and updated metadata.

The API allows for retrieving the latest version of the collection, or a specific version.

B.6.1 Dynamic or static Collection objects

The TCO is managed by the TEA software platform. There are two ways to implement this:

  • Dynamic: The TCO is built for each API request and created dynamically.
  • Static: The TCO is built at publication time as a static object by the publisher. This object can be digitally signed at publication time and version controlled.

B.6.2 Structure

The TEA Collection object has the following parts:

  • Preamble
  • uuid: UUID of the TEA Collection object. A TEA Collection shall use the same UUID as its parent Product Release or Component Release. Within an API base, a Product Release and a Component Release shall not share a UUID. Consequently, Collections belonging to different parent releases have different UUIDs. Versions of the same Collection retain the same UUID. See TEA UUID Scope and Stability.
  • version: TEA Collection version, incremented by 1 each time its content changes. Versions start with 1. Content changes include replacing an embedded artifact with a newer revision (for example one published because an external url or signatureUrl changed). If a Collection adopts that new artifact revision, the server shall publish a new Collection version. Previously published Collection versions shall remain unchanged. Classification of that adoption follows the update-reason rules below.
  • createdDate: Timestamp when the TEA Collection version was created.
  • belongsTo: Indicates whether this collection belongs to a Component Release or a Product Release. Enum values COMPONENT_RELEASE or PRODUCT_RELEASE.
  • updateReason: Reason for the update/release of the TEA Collection object.
  • artifacts: Array of TEA Artifact objects. See below.

Required fields:

  • uuid, version, createdDate, belongsTo, updateReason, artifacts, updateReason.type

B.6.3 The TEA Artifact object

A TEA Artifact object represents a security-related document or file linked to a component release, such as an SBOM, VEX, attestation, or license. TEA Artifacts are strictly immutable per revision: if the underlying document or any published field, including external url / signatureUrl values, changes, a new TEA Artifact revision shall be created. For a fixed artifact UUID, version, and format, the server shall ensure that successful content retrieval through its download endpoint, including retrieval after following redirects, yields unchanged artifact bytes after HTTP transfer coding and content coding are removed. The server shall ensure that successful signature retrieval through its signature download endpoint yields unchanged signature bytes on the same terms. Changing only a download response's Location, or only its HTTP content coding, while preserving those bytes, does not require a new artifact or collection version. For artifact content retrieved from an external url, the published checksums are the integrity statement for the revision. These checksums do not cover detached signatures.

TEA Artifacts can be reused across multiple TEA Collections, allowing the same document to be referenced by different component or product releases. This promotes consistency and reduces duplication. Publishing a new artifact revision does not by itself change Collections that continue to embed an older revision.

Optionally, each TEA Artifact can specify the distributionIds of the distributions it applies to. If this field is absent, the TEA Artifact is considered applicable to all distributions of the release.

B.6.3.1 Structure

A TEA Artifact object contains the following fields:

  • uuid: The UUID of the TEA Artifact object. Together with version uniquely identifies the TEA Artifact.
  • version: Revision number, starting at 1 and incremented by 1 for each new revision of the same artifact UUID. Together with uuid uniquely identifies the TEA Artifact. Successive revisions cover content changes and changes to any published field, including external url or signatureUrl values. Each published revision is immutable.
  • name: A human-readable name for the artifact.
  • type: The type of TEA artifact. See TEA Artifact types for allowed values (e.g., BOM, VULNERABILITIES, LICENSE).
  • createdDate: The date and time the TEA Artifact revision was created.
  • distributionIds: (optional): Array of TEA Component Release distributions that this TEA Artifact applies to. If absent or empty, the TEA Artifact applies to all distributions.
  • formats:
    A non-empty array of objects, each representing the same artifact content in a different format. The order of the list is not significant. Each format object includes:
    • mediaType: The media type of the document (e.g., application/vnd.cyclonedx+xml). Required. A media type appears at most once across the formats of a TEA Artifact revision, so that a format can be selected unambiguously by media type.

    • description: A free-text description of the artifact format.

    • url (optional): An external download URL for the artifact, outside the TEA API. When present, clients shall retrieve the content from it. When absent, the TEA server hosts the content itself and clients shall retrieve it from the artifact download endpoint (/artifact/{uuid}/{version}/download), selecting the format by its media type. url and signatureUrl should be stable URLs. Servers should not publish pre-signed or otherwise expiring URLs in them. A server that serves content from expiring storage links shall omit them and answer from the download endpoints, with 302 where the bytes live elsewhere. Changing url shall create a new artifact revision, even when content and checksums are unchanged. The server shall preserve the URLs published on each historical artifact and collection version. Collection adoption follows the collection version rules above. Byte stability for content retrieved through the server's download endpoint follows the artifact revision rule above. Servers shall publish at least one checksum for every format that has a url; content that does not match them is not the content of that revision. The latest download endpoints are mutable by design and shall not be used as a format's url or signatureUrl.

    • signatureUrl (optional): An external download URL for a detached digital signature of the artifact, outside the TEA API. If present, clients retrieve the signature from it. If absent, clients retrieve it from the artifact signature download endpoint (/artifact/{uuid}/{version}/signature/download), which answers 404 when no signature is published for the format. Changing signatureUrl follows the same revision and collection-adoption rules as url. Byte stability for signature retrieval through the server's signature download endpoint follows the artifact revision rule above.

    • checksums: When present, the array shall contain at least one entry. When url is present, checksums is required. An array of checksum objects for the artifact format's content bytes, each containing:

      • algType: The checksum algorithm used (e.g., SHA-256, SHA3-512).
      • algValue: The checksum value as a string. When url is present, these checksums are the integrity statement for the revision. Content that does not match them is not the content of that revision.

      Published checksums shall be calculated over the artifact format's bytes before HTTP content coding is applied. Clients verifying them shall first remove any HTTP transfer coding and content coding, and shall not otherwise transform or canonicalize the artifact bytes. An artifact that is itself compressed, such as a .gz file, stays in that form. The TEA servers shall not declare the artifact's own compression as HTTP content coding, because clients would then remove it and the checksum would not match.

Required fields:

  • uuid, type, formats, createdDate, version

B.6.3.2 Notes

  • The formats array allows the same artifact to be provided in multiple encodings or serializations (e.g., JSON, XML).
  • The checksums field provides integrity verification for each artifact format's bytes before HTTP content coding is applied. It does not cover detached signatures, and it is not a digest of an HTTP-encoded representation; Repr-Digest covers that.
  • Detached signatures, whether at signatureUrl or served by the TEA server, enable consumers to verify the authenticity of the artifact.
  • url and signatureUrl are always external locations; a TEA server that hosts content or signatures itself omits them and serves the bytes from its download endpoints. A TEA access token is sent only to the TEA server's own API, never to an external URL.

B.6.4 The reason for TCO update enum

Table 129: TEA Collection update reasons
ENUM Description
INITIAL_RELEASE Initial release of the collection
VEX_UPDATED Adding or revising an artifact of type VULNERABILITIES, including a new revision whose external url or signatureUrl changed
ARTIFACT_UPDATED A new revision of an artifact whose type is not VULNERABILITIES, including a revision whose external url or signatureUrl changed
ARTIFACT_REMOVED Removal of artifact
ARTIFACT_ADDED Addition of an artifact whose type is not VULNERABILITIES

Replacing an embedded artifact revision solely because its published url or signatureUrl changed is VEX_UPDATED when the artifact type is VULNERABILITIES, and ARTIFACT_UPDATED otherwise. VEX_UPDATED covers adding or revising an artifact of type VULNERABILITIES. VEX and VDR share that type. Removing an artifact, including one of type VULNERABILITIES, counts as ARTIFACT_REMOVED. The first Collection version shall use INITIAL_RELEASE. In subsequent versions, adding or revising an artifact of type VULNERABILITIES counts as VEX_UPDATED. When multiple change kinds occur, the server shall select updateReason.type using the precedence rule below.

When a collection version other than the first contains changes of more than one kind, the server shall set updateReason.type to the first applicable value in this order: VEX_UPDATED, ARTIFACT_REMOVED, ARTIFACT_ADDED, ARTIFACT_UPDATED. comment can describe the other changes. A client that needs the complete set of changes should compare the version with the previous one.

Updates of VEX (CSAF) files may be handled in a different way by a TEA client, producing different alerts than other changes of a collection.

B.6.5 TEA Artifact types

Table 130: TEA Artifact types
ENUM Description
ATTESTATION Machine-readable statements containing facts, evidence, or testimony.
BOM Bill of Materials: SBOM, OBOM, HBOM, SaaSBOM, etc.
BUILD_META Build-system specific metadata file: pom.xml, package.json, .nuspec, etc.
CERTIFICATION Industry, regulatory, or other certification from an accredited certification body.
FORMULATION Describes how a component or service was manufactured or deployed.
LICENSE License file
RELEASE_NOTES Release notes document
SECURITY_TXT A security.txt file
THREAT_MODEL A threat model
VULNERABILITIES A list of vulnerabilities: VDR/VEX
OTHER Document that does not fall into any of the above categories

B.6.5.1 Examples

{
  "uuid": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab",
  "version": 10,
  "createdDate": "2024-12-15T00:00:00Z",
  "belongsTo": "COMPONENT_RELEASE",
  "updateReason": {
    "type": "VEX_UPDATED",
    "comment": "VDR file updated"
  },
  "artifacts": [
    {
      "uuid": "1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce",
      "version": 2,
      "createdDate": "2024-12-13T00:00:00Z",
      "name": "Build SBOM",
      "type": "BOM",
      "formats": [
        {
          "mediaType": "application/vnd.cyclonedx+xml",
          "description": "CycloneDX SBOM (XML)",
          "url": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml",
          "signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3-cyclonedx.xml.asc",
          "checksums": [
            {
              "algType": "SHA-256",
              "algValue": "e04c9d55986d7194822eaa4f8115a77f801844d807ad6e0d454ac31dd41861e5"
            },
            {
              "algType": "SHA-1",
              "algValue": "5a7d4caef63c5c5ccdf07c39337323529eb5a770"
            }
          ]
        }
      ]
    },
    {
      "uuid": "dfa35519-9734-4259-bba1-3e825cf4be06",
      "version": 7,
      "createdDate": "2024-12-15T00:00:00Z",
      "name": "Vulnerability Disclosure Report",
      "type": "VULNERABILITIES",
      "formats": [
        {
          "mediaType": "application/vnd.cyclonedx+xml",
          "description": "CycloneDX VDR (XML)",
          "url": "https://logging.apache.org/cyclonedx/vdr.xml",
          "checksums": [
            {
              "algType": "SHA-256",
              "algValue": "75b81020b3917cb682b1a7605ade431e062f7a4c01a412f0b87543b6e995ad2a"
            }
          ]
        }
      ]
    }
  ]
}

Bibliography

Colophon

This specification is authored on GitHub in a plaintext source format called Ecmarkup. Ecmarkup is an HTML and Markdown dialect that provides a framework and toolset for authoring Ecma specifications in plaintext and processing the specification into a full-featured HTML rendering that follows the editorial conventions for this document. Ecmarkup builds on and integrates a number of other formats and technologies including Grammarkdown for defining syntax and Ecmarkdown for authoring algorithm steps. PDF renderings of this specification are produced using a print stylesheet which takes advantage of the CSS Paged Media specification and is converted using PrinceXML.

The body of this Specification is assembled from two sources of truth held in the Transparency Exchange API source repository: the OpenAPI document at spec/openapi.yaml, from which the API surface and data model are generated; and a set of Markdown documents which carry the narrative chapters and are imported verbatim. The build pipeline in this repository fetches both, converts them to Ecmarkup HTML, and renders them via the standard Ecmarkup toolchain.

We extend our gratitude to TC39 for their exceptional work in developing Ecmarkup, which has greatly facilitated TC54's successful adoption of this tool for the preparation and maintenance of our technical specifications.

Copyright & Software License

Ecma International

Rue du Rhone 114

CH-1204 Geneva

Tel: +41 22 849 6000

Fax: +41 22 849 6001

Web: https://ecma-international.org/

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.