?uem/p1-90`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.
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
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.
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.
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:
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.
Standards and requirements along with attestations to those standards and requirements are captured and supported by
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,
Product lifecycle events are communicated through the
Inclusion of
If
The Transparency Exchange API standard is created by OWASP
For more information of these and releated standards, visit https://tc54.org
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.
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
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,
https://ecma-international.org/publications-and-standards/standards/ecma-424/
ECMA-427, Package-URL (
https://ecma-international.org/publications-and-standards/standards/ecma-427/
ECMA-428, Common Lifecycle Enumeration (
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 (
https://www.rfc-editor.org/info/rfc3986/
IETF RFC 6749, The
https://www.rfc-editor.org/info/rfc6749/
IETF RFC 6750, The
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 (
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 (
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,
https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-validation-01
SemVer 2.0.0
https://semver.org/spec/v2.0.0.html
For the purposes of this Standard, the following terms and definitions apply:
machine-readable statement containing facts, evidence, or testimony
authn
process of verifying the identity of a principal
authz
process of determining what a verified principal is permitted to do
versioned list of the TEA Artifacts of one Component Release or one Product Release
A Collection has the same
document describing the compliance, certification or regulatory status of a Component, for example a SOC 2 report
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.
software or hardware item whose successive versions are Component Releases
A Product Release can reference Components and specific Component Releases.
specific version of a Component
Each Component Release has its own Collection.
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
item sold, distributed or otherwise delivered under one name
specific version of a Product that can be acquired or downloaded
SBOM
structured inventory of the software components of a product, with their versions, identifiers and dependencies
security-related document, such as an SBOM, a VEX document or an attestation, published in one or more formats and identified by a
software that retrieves information from a TEA server using the API defined in this Standard
server that implements the API defined in this Standard
TEI
tei://<domain-name>/<type>/<unique-identifier> that identifies one or more Product Releases
The domain name of a TEI is used to locate the TEA server; see Clause
party that publishes TEIs for its Product Releases
A vendor can be a commercial company or an open source project.
VEX document
document stating, for a product, the exploitability status of known vulnerabilities
A VEX document states, for example, whether a vulnerability affects the product, does not affect it, or is mitigated.
For the purposes of this Standard, the following abbreviations apply:
| Abbreviation | |
|---|---|
| API | Application Programming Interface |
| CPE | Common Platform Enumeration, a naming scheme for IT products and platforms, usable as an identifier type |
| 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 |
| Universally Unique Identifier | |
| VDR | Vulnerability Disclosure Report |
| VEX | Vulnerability Exploitability eXchange |
Discovery is the first step in all TEA interactions, enabling a consumer to map an identifier to a service endpoint.
This Standard defines:
TEA separates:
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,
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.
The TEI for a product release can be communicated to the user in many ways.
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.
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
There is no registry of TEIs; only TEI types are registered.
The TEI, Transparency Exchange Identifier, is a URL schema that is extensible based on existing identifiers like EAN codes,
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.
A TEI is a
tei://<domain-name>/<type>/<unique-identifier>
tei.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.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.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.
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.
| Type | Unique identifier | Example |
|---|---|---|
purl |
tei://example.com/purl/cGtnOm1hdmVuL2Nv |
|
hash |
Hash of an object, <hashtype>:<hex> |
tei://example.com/hash/SHA-256:fd44efd601f6 |
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 |
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:
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:
tei in lowercase,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.
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-1a52914d44b2tei://<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
This results in the base URL such as https://products.example.com/.well-known/tea
This response shall contain a JSON object that lists the available TEA server endpoints and supported versions. The JSON shall conform to the
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
}
]
}
Discovery documents may be cached.
Implementations should:
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
Discovery proceeds in two stages that share the same retry, backoff, and attempt-bound rules below:
/.well-known/tea for the TEI’s domain host/discovery on a selected API base URL constructed from a well-known endpoint entry.well-known/teaClients 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 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 [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 [
Examples:
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-1a52914d44b1tei://products.example.com/purl/cGtnOmRlYi9kZWJpYW4vY3VybEA3LjUwLjMtMT9hcmNoPWkzODYmZGlzdHJvPWplc3NpZQ https://api2.example.com/mytea/v1.0.0/discovery?tei=tei%3A//products.example.com/purl/cGtnOmRlYi9kZWJpYW4vY3VybEA3LjUwLjMtMT9hcmNoPWkzODYmZGlzdHJvPWplc3NpZQThe discovery endpoint is a part of the TEA /token, /discovery is required on a conforming TEA API base: a conforming server that exposes a given API version shall implement it.
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 — servers — non-empty array of server-info objects (rootUrl, versions, and optional priority).well-known/tea and servers[] are related but distinct:
/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"]
}
]
}
]
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 .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.
If the server does not resolve the requested TEI or /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:
/discovery is missing, and shall not fail over to another endpoint solely because of the response;error value received; andA 404 that is not a TEA error response is a failed attempt; see 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:
5xx from the host being contacted404 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).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.
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" (
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.
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.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.
Common errors:
/discovery, a TEA error response (application/json body with a string error property, typically OBJECT_UNKNOWN): this server does not resolve the TEI or error value; do not report that as evidence that no updates are available.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.Clients should:
Servers shall not locate the actual TEA service endpoint at the /.well-known/tea
HTTP is the protocol. http and https are 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://products.example.com/uuid/d4d9f54a-abcf-11ee-ac79-1a52914d44b1https://products.example.com/.well-known/teaConforming 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.
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.
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.
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:
POST /token) described below, and shall support the API key credential exchange on it.Two consequences are worth stating explicitly, because they are what make the baseline useful:
The token endpoint is POST /token, relative to the TEA API base URL, and is defined in the TEA
/token appears only in its examples - so TEA fixes the path here rather than requiring clients to discover it. TEA defines no
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
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 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.
A successful response is the standard
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 invalid_client for a bad API key or unsupported_grant_type for a grant the server does not implement.
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
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
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: 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
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
| 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 |
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.
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.
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.
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
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:
200 with the resource. The client is done.401 with a WWW-Authenticate header naming the Bearer scheme, as described in 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 /token allows alternate client authentication (for example, mutual TLS, Authorization: Bearer <access_token>, and presents the same token on subsequent requests until it expires or is rejected.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.
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
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:
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.
Servers that delegate identity to an external provider may publish 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.
X-API-KeyThere 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
This document defines the scope of uniqueness and the stability guarantees of
Paths such as /productRelease/{uuid} name an object by the API base and the
A TEA
API base + object type + UUID
tei://<domain-name>/<type>/<unique-identifier>); see discovery. It tells a client which API to call. It is not part of a If two authoritative domains would assign the same
Exception: Product Release and Component Release. A TEA Collection shall use the same
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
Implementations may use any
All TEA
Stability is required for all TEA object types, not only TEA Product Release. While TEI resolution targets only Product Release /component/{uuid}, /componentRelease/{uuid}, /productRelease/{uuid}); changing those
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
| Scheme | Type | Description |
|---|---|---|
bearerAuth |
http bearer |
A TEA access token obtained from 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 |
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 (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).
GET/discovery
Discovery endpoint which resolves an identifier into one or more product release
Exactly one of the tei and purl query parameters shall be provided. A request with neither, or with both, is rejected with 400.
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
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
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.3Unlike /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.
| 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 |
| Status | Description | Schema |
|---|---|---|
200 |
Non-empty array of discovery results for the requested TEI or 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/products
Returns a list of TEA products. Note that multiple products may match.
| 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 The token represents continuation state for the original query, including A Servers shall return |
sortField |
query | No | string (enum) |
The field by which to sort the results. Paginated results shall be ordered first by the selected One of: |
sortOrder |
query | No | string (enum) |
The direction of the sort. The default is The selected sort order applies to both the primary One of: |
| 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 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 |
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 |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/product/{uuid}
Get a TEA Product by
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/product/{uuid}/releases
Get releases of the product
| Name | In | Required | Type | Description |
|---|---|---|---|---|
uuid |
path | Yes | uuid |
|
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 The token represents continuation state for the original query, including A Servers shall return |
sortField |
query | No | string (enum) |
The field by which to sort the results. Paginated results shall be ordered first by the selected When When One of: |
sortOrder |
query | No | string (enum) |
The direction of the sort. The default is The selected sort order applies to both the primary One of: |
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/productReleases
Returns a list of TEA product releases. Note that multiple product releases may match.
| 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 The token represents continuation state for the original query, including A Servers shall return |
sortField |
query | No | string (enum) |
The field by which to sort the results. Paginated results shall be ordered first by the selected When When One of: |
sortOrder |
query | No | string (enum) |
The direction of the sort. The default is The selected sort order applies to both the primary One of: |
| 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 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 |
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 |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/productRelease/{uuid}
Get the TEA Product Release with its latest collection
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/components
Returns a list of TEA components. Note that multiple components may match.
| 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 The token represents continuation state for the original query, including A Servers shall return |
sortField |
query | No | string (enum) |
The field by which to sort the results. Paginated results shall be ordered first by the selected One of: |
sortOrder |
query | No | string (enum) |
The direction of the sort. The default is The selected sort order applies to both the primary One of: |
| 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 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 |
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 |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/component/{uuid}
Get a TEA Component
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/component/{uuid}/releases
Get releases of the component
| Name | In | Required | Type | Description |
|---|---|---|---|---|
uuid |
path | Yes | uuid |
|
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 The token represents continuation state for the original query, including A Servers shall return |
sortField |
query | No | string (enum) |
The field by which to sort the results. Paginated results shall be ordered first by the selected When When One of: |
sortOrder |
query | No | string (enum) |
The direction of the sort. The default is The selected sort order applies to both the primary One of: |
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/componentReleases
Returns a list of TEA component releases. Note that multiple component releases may match.
| 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 The token represents continuation state for the original query, including A Servers shall return |
sortField |
query | No | string (enum) |
The field by which to sort the results. Paginated results shall be ordered first by the selected When When One of: |
sortOrder |
query | No | string (enum) |
The direction of the sort. The default is The selected sort order applies to both the primary One of: |
| 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 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 |
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 |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/componentRelease/{uuid}
Get the TEA Component Release with its latest collection
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/productRelease/{uuid}/collections
Get the TEA Collections belonging to the TEA Product Release
| Name | In | Required | Type | Description |
|---|---|---|---|---|
uuid |
path | Yes | uuid |
|
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 The token represents continuation state for the original query, including A Servers shall return |
sortField |
query | No | string (enum) |
The field by which to sort the results. Paginated collection results shall be ordered first by the selected The only currently supported collection One of: |
sortOrder |
query | No | string (enum) |
The direction of the sort. The default is The selected sort order applies to both the primary One of: |
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
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.
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/productRelease/{uuid}/collection/{collectionVersion}
Get a specific Collection (by version) for a TEA Product Release by its
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/componentRelease/{uuid}/collections
Get the TEA Collections belonging to the TEA Component Release
| Name | In | Required | Type | Description |
|---|---|---|---|---|
uuid |
path | Yes | uuid |
|
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 The token represents continuation state for the original query, including A Servers shall return |
sortField |
query | No | string (enum) |
The field by which to sort the results. Paginated collection results shall be ordered first by the selected The only currently supported collection One of: |
sortOrder |
query | No | string (enum) |
The direction of the sort. The default is The selected sort order applies to both the primary One of: |
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
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.
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/componentRelease/{uuid}/collection/{collectionVersion}
Get a specific Collection (by version) for a TEA Component Release by its
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/artifact/{uuid}/latest
Get metadata for the latest revision of a specific TEA Artifact, that is, the revision with the greatest published version.
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
uuid |
path | Yes | uuid |
|
mediaType |
query | No | string |
Selects which of the artifact revision's Matching against a format's Example after serialization: |
If-None-Match |
header | No | string | Conditional request validator (ETag is the only defined validator. Servers evaluate If-None-Match with the weak comparison function (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. |
| 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 |
string |
302 |
The selected representation is available at another location, for example object storage addressed by a pre-signed URL. The client follows the Changing only this response's 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 (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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
406 |
The artifact revision exists, but has no format matching the requested
|
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
200 |
Content-Disposition |
string | Suggested filename for the artifact content, as an attachment disposition per |
200 |
Content-Encoding |
string | HTTP content codings applied to the selected representation, listed in the order applied (.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 As with versioned downloads, responses containing access-controlled content shall use |
200 |
Content-Location |
string | Absolute URL of the versioned content download for the revision and format this response was resolved to, per 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 If changing or removing the |
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 |
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 |
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
uuid |
path | Yes | uuid |
|
mediaType |
query | No | string |
Selects which of the artifact revision's Matching against a format's Example after serialization: |
If-None-Match |
header | No | string | Conditional request validator (ETag is the only defined validator. Servers evaluate If-None-Match with the weak comparison function (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. |
| 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 |
string |
302 |
The selected representation is available at another location, for example object storage addressed by a pre-signed URL. The client follows the Changing only this response's 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 (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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
406 |
The artifact revision exists, but has no format matching the requested
|
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
200 |
Content-Disposition |
string | Suggested filename for the signature, as an attachment disposition per |
200 |
Content-Encoding |
string | HTTP content codings applied to the selected representation, listed in the order applied (.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 As with versioned downloads, responses containing access-controlled content shall use |
200 |
Content-Location |
string | Absolute URL of the versioned signature download for the revision and format this response was resolved to, per 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 If changing or removing the |
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 |
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 |
GET/artifact/{uuid}/{artifactVersion}
Get metadata for a specific revision of a specific TEA Artifact
| 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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
uuid |
path | Yes | uuid |
|
artifactVersion |
path | Yes | integer | Version of TEA Artifact |
mediaType |
query | No | string |
Selects which of the artifact revision's Matching against a format's Example after serialization: |
If-None-Match |
header | No | string | Conditional request validator (ETag is the only defined validator. Servers evaluate If-None-Match with the weak comparison function (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. |
| Status | Description | Schema |
|---|---|---|
200 |
The content of the requested TEA Artifact format. The wire |
string |
302 |
The selected representation is available at another location, for example object storage addressed by a pre-signed URL. The client follows the Changing only this response's 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 (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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
406 |
The artifact revision exists, but has no format matching the requested
|
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
200 |
Content-Disposition |
string | Suggested filename for the artifact content, as an attachment disposition per |
200 |
Content-Encoding |
string | HTTP content codings applied to the selected representation, listed in the order applied (.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 Responses containing access-controlled content shall use |
200 |
Content-Location |
string | Absolute URL of the versioned content download for the revision and format this response was resolved to, per 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 If changing or removing the |
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 |
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 |
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.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
uuid |
path | Yes | uuid |
|
artifactVersion |
path | Yes | integer | Version of TEA Artifact |
mediaType |
query | No | string |
Selects which of the artifact revision's Matching against a format's Example after serialization: |
If-None-Match |
header | No | string | Conditional request validator (ETag is the only defined validator. Servers evaluate If-None-Match with the weak comparison function (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. |
| Status | Description | Schema |
|---|---|---|
200 |
The detached signature for the selected format of the TEA Artifact revision. The wire |
string |
302 |
The selected representation is available at another location, for example object storage addressed by a pre-signed URL. The client follows the Changing only this response's 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 (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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
406 |
The artifact revision exists, but has no format matching the requested
|
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
200 |
Content-Disposition |
string | Suggested filename for the signature, as an attachment disposition per |
200 |
Content-Encoding |
string | HTTP content codings applied to the selected representation, listed in the order applied (.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 Responses containing access-controlled content shall use |
200 |
Content-Location |
string | Absolute URL of the versioned signature download for the revision and format this response was resolved to, per 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 If changing or removing the |
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 |
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 |
GET/product/{uuid}/cle
Get the
| Status | Description | Schema |
|---|---|---|
200 |
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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/productRelease/{uuid}/cle
Get the
| Status | Description | Schema |
|---|---|---|
200 |
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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/component/{uuid}/cle
Get the
| Status | Description | Schema |
|---|---|---|
200 |
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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
GET/componentRelease/{uuid}/cle
Get the
| Status | Description | Schema |
|---|---|---|
200 |
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 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 |
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 |
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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
401 |
WWW-Authenticate |
string | Bearer challenge, as defined in |
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 (
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 (
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, 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;
Security: basicAuth or none (anonymous access)
Request body:
application/x-www-form-urlencoded—token-request (required)
| 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 (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:
Concealment applies only after authentication. A request to a protected object with no valid access token shall receive |
error-response |
| Status | Header | Type | Description |
|---|---|---|---|
200 |
Cache-Control |
string | Servers shall set no-store on token responses ( |
401 |
WWW-Authenticate |
string | Challenge indicating the client authentication methods supported by the token endpoint. |
This section catalogues the named schemas declared in components.schemas.
A security-related document
Type: object
| Property | Type | Requirement | Description |
|---|---|---|---|
uuid |
uuid |
Required | The |
version |
integer | Required | Revision number, starting at 1 and incremented by 1 for each new revision of the same artifact 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 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. |
{
"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"
}
]
}
]
}{
"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"
}
]
}
]
}A security-related document in a specific format
Type: object
| Property | Type | Requirement | Description |
|---|---|---|---|
mediaType |
string | Required |
The Media Type of the document. A media type shall appear at most once across the |
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,
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 Byte stability for content retrieved through the server's download endpoint follows The TEA server does not control the bytes behind an external Format: |
signatureUrl |
string | Optional |
External download URL for a detached signature of this format of the TEA Artifact. As with This specification does not define which signature technology is used, nor model the signing algorithm, key, or certificate chain. Format: |
checksums |
Array of checksum |
Optional |
Checksums for this artifact format's content bytes (the payload retrieved from 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 |
Type of TEA Artifact.
Type: string
| Value |
|---|
ATTESTATION |
BOM |
BUILD_META |
CERTIFICATION |
FORMULATION |
LICENSE |
RELEASE_NOTES |
SECURITY_TXT |
THREAT_MODEL |
VULNERABILITIES |
OTHER |
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
| 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]+$. |
Checksum algorithm
Type: string
| Value |
|---|
SHA-1 |
SHA-256 |
SHA-384 |
SHA-512 |
SHA3-256 |
SHA3-384 |
SHA3-512 |
BLAKE2b-256 |
BLAKE2b-384 |
BLAKE2b-512 |
BLAKE3 |
Lifecycle events for the object this endpoint is called on, as a TEA projection of the Common Lifecycle Enumeration (
This is not a $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 OTHER until a dedicated type exists; the same artifact may be referenced from more than one collection. The
Mapping to
identifiers[] on componentRenamed uses the TEA identifier shape (idType, idValue); type / value with the same meaning.{ version } names one version without a vers scheme, because a TEA server does not always know the package ecosystem. It corresponds to the vers:<scheme>/<version> once the scheme is known. { range } is a cle-event is one flat object. The fields Selection. Servers shall return in events a subset of the events of the 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 200, with an empty events array when no event has been recorded yet. A server that does not provide 404 with error: NOT_IMPLEMENTED; error: OBJECT_UNKNOWN means the object itself is unknown.
Type: object
| Property | Type | Requirement | Description |
|---|---|---|---|
events |
Array of cle-event |
Required | Array of |
definitions |
cle-definitions |
Optional | Container for reusable policy definitions referenced by events |
{
"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"
}
]
}
}Container for reusable
Type: object
| Property | Type | Requirement | Description |
|---|---|---|---|
support |
Array of cle-support-definition |
Optional | List of support policies |
A discrete lifecycle event from the
date-time schema: UTC with the Z designator, fractional seconds preserved. A +00:00 offset in an upstream Z. Any other offset is not UTC and is not valid
Type: object
| 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 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 |
{
"id": 1,
"type": "released",
"effective": "2024-01-01T00:00:00Z",
"version": "1.0.0",
"license": "MIT",
"published": "2023-06-01T00:00:00Z"
}{
"id": 3,
"type": "endOfSupport",
"effective": "2024-01-01T00:00:00Z",
"versions": [
{
"version": "1.0.0"
}
],
"supportId": "standard",
"published": "2023-06-01T00:00:00Z"
}The type of
Type: string
| Value |
|---|
released |
endOfDevelopment |
endOfSupport |
endOfLife |
endOfDistribution |
endOfMarketing |
supersededBy |
componentRenamed |
withdrawn |
A support policy definition from
Type: object
| 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. |
{
"id": "standard",
"description": "Standard product support policy",
"url": "https://example.com/support/standard"
}Which versions an event affects. Exactly one of version or range. range is an 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
| 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") |
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
| Property | Type | Requirement | Description |
|---|---|---|---|
uuid |
uuid |
Required | 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). |
{
"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"
}
]
}
]
}
]
}Indicates whether a collection belongs to a component release or a product release
Type: string
| Value |
|---|
COMPONENT_RELEASE |
PRODUCT_RELEASE |
Reason for the update to the TEA collection
Type: object
| Property | Type | Requirement | Description |
|---|---|---|---|
type |
collection-update-reason-type |
Required | Type of update reason. |
comment |
string | Optional | Free text description |
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
| Value |
|---|
INITIAL_RELEASE |
VEX_UPDATED |
ARTIFACT_UPDATED |
ARTIFACT_ADDED |
ARTIFACT_REMOVED |
Well-known compliance document types. When idType is COMPLIANCE_DOCUMENT, the idValue shall be one of these values.
Type: string
| 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 |
A TEA component
Type: object
| 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 |
{
"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"
}
]
}{
"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"
}
]
}A reference to a TEA component or specific component release
Type: object
| Property | Type | Requirement | Description |
|---|---|---|---|
uuid |
uuid |
Required | A unique identifier for the TEA component |
release |
uuid |
Optional | Optional |
A TEA Component Release
Type: object
| 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 | |
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 |
{
"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"
}
]
}{
"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"
}
]
}{
"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"
}
]
}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.
| Property | Type | Requirement | Description |
|---|---|---|---|
latestCollection |
collection |
Required | The latest TEA Collection for this component release |
{
"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"
}
]
}
]
}
]
}
}Timestamp, 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$
2024-03-20T15:30:00Z
Discovery information for one product release matched by a TEI or /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
| Property | Type | Requirement | Description |
|---|---|---|---|
productReleaseUuid |
uuid |
Required | |
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. |
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
| Property | Type | Requirement | Description |
|---|---|---|---|
error |
unknown-error-type |
Required | |
message |
string | Optional | Optional human-readable explanation for diagnostics. Clients shall not interpret it programmatically. |
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
| Property | Type | Requirement | Description |
|---|---|---|---|
idType |
identifier-type |
Required | Type of identifier, e.g. TEI, PURL, CPE |
idValue |
string | Required | Identifier value |
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
Type: string
| Value |
|---|
CPE |
TEI |
PURL |
COMPLIANCE_DOCUMENT |
A paginated response containing TEA Collections
Includes all properties of pagination-details.
| Property | Type | Requirement | Description |
|---|---|---|---|
results |
Array of collection |
Required |
{
"hasNext": true,
"nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0",
"results": []
}{
"hasNext": false,
"results": []
}A paginated response containing TEA Component Releases
Includes all properties of pagination-details.
| Property | Type | Requirement | Description |
|---|---|---|---|
results |
Array of component-release |
Required |
{
"hasNext": true,
"nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0",
"results": []
}{
"hasNext": false,
"results": []
}A paginated response containing TEA Components
Includes all properties of pagination-details.
| Property | Type | Requirement | Description |
|---|---|---|---|
results |
Array of component |
Required |
{
"hasNext": true,
"nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0",
"results": []
}{
"hasNext": false,
"results": []
}A paginated response containing TEA Product Releases
Includes all properties of pagination-details.
| Property | Type | Requirement | Description |
|---|---|---|---|
results |
Array of product-release |
Required |
{
"hasNext": true,
"nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0",
"results": []
}{
"hasNext": false,
"results": []
}A paginated response containing TEA Products
Includes all properties of pagination-details.
| Property | Type | Requirement | Description |
|---|---|---|---|
results |
Array of product |
Required |
{
"hasNext": true,
"nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0",
"results": []
}{
"hasNext": false,
"results": []
}Type: object
| Property | Type | Requirement | Description |
|---|---|---|---|
hasNext |
boolean | Required |
A flag indicating whether there is another page of results to fetch. When Default: |
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": true,
"nextPageToken": "eyJwYWdlIjoiY29udGludWF0aW9uIn0"
}{
"hasNext": false
}A TEA product
Type: object
| 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, |
{
"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"
}
]
}A specific release of a TEA product
Type: object
| 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 | |
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": "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"
}
]
}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.
| Property | Type | Requirement | Description |
|---|---|---|---|
latestCollection |
collection |
Required | The latest TEA Collection for this product release |
{
"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": []
}
}Type: object
| 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). |
{
"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"
}TEA server information including URL, versions, and optional priority
Type: object
| 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 /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. |
Token error response, as defined in
Type: object
| Property | Type | Requirement | Description |
|---|---|---|---|
error |
string (enum) | Required | Error code as defined in 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 | Format: uri. |
Token request for the client_credentials grant, as defined in scope parameter applies to both. The assertion parameter applies only to assertion grants. /token description).
Type: object
| Property | Type | Requirement | Description |
|---|---|---|---|
grant_type |
string | Required | 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 ( |
assertion |
string | Optional | Assertion value, when an assertion grant type is used ( |
Successful token response, as defined in
Type: object
| 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. |
Classification of TEA error response
Type: string
| Value |
|---|
OBJECT_UNKNOWN |
NOT_IMPLEMENTED |
NO_ACCEPTABLE_FORMAT |
SIGNATURE_NOT_FOUND |
INVALID_REQUEST |
INVALID_PAGE_TOKEN |
A
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}$
This annex specifies the schema for the TEA /.well-known/tea discovery document. The schema is expressed in JSON Schema draft-07 (
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.
| 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. |
{
"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
}
]
}Type: object
Additional properties are not permitted.
| 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 ^(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. |
The following sections are derived from the working group's authoring notes maintained as Markdown in the source repository.
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.
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.
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).
In this case, the client wants to search for a specific product release using the API
In this case a TEA client knows the component
In this case a TEA client knows the release
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.
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 (
Authorization can be done on multiple levels, including which products and versions are supported for a specific user.
A TEA Product Release will be the starting point of discovery. The TEA product release will list all included components with the
The TEA Product object groups multiple releases together.
Key attributes:
TEI, PURL, CPERequired fields:
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.
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.
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:
Required fields:
Collections for a product release contain artefacts relevant to that product release.
The following example is reused from the 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"
}
]
}
The "Pre-release" flag is used to indicate that this is not a final release. For a given product release with a
If the final version is different from the pre-release (bugs fixed, code changed, different binary) a new product release with a new
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.
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.
A TEA Component object has the following parts:
TEI, PURL, CPERequired fields:
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"
}
]
}
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.
Each distribution is assigned a distributionId, 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:
Collections for a release contain artifacts relevant to that specific release.
Required fields:
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:
Required fields:
The following examples are reused from the 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"
}
]
} 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.
{
"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"
}
]
}
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:
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.
{
"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"
}
]
}
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:
releaseDate attribute. Once the release is approved, the preRelease flag is set to false and the releaseDate is added.releaseDate, but preRelease remains true.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"
}
]
} 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"
}
]
} 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:
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
The API allows for retrieving the latest version of the collection, or a specific version.
The TCO is managed by the TEA software platform. There are two ways to implement this:
The TEA Collection object has the following parts:
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.COMPONENT_RELEASE or PRODUCT_RELEASE.Required fields:
uuid, version, createdDate, belongsTo, updateReason, artifacts, updateReason.typeA 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 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.
A TEA Artifact object contains the following fields:
url or signatureUrl values. Each published revision is immutable.BOM, VULNERABILITIES, LICENSE).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:
SHA-256, SHA3-512).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, versionformats array allows the same artifact to be provided in multiple encodings or serializations (e.g., JSON, XML).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.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.| 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 (
| 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 |
{
"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"
}
]
}
]
}
]
}
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 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.
Ecma International
Rue du Rhone 114
CH-1204 Geneva
Tel: +41 22 849 6000
Fax: +41 22 849 6001
Web: https://ecma-international.org/
COPYRIGHT NOTICE
© 2026 Ecma International
By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.
This document may be copied, published and distributed to others, and certain derivative works of it may be prepared, copied, published, and distributed, in whole or in part, provided that the above copyright notice and this Copyright License and Disclaimer are included on all such copies and derivative works. The only derivative works that are permissible under this Copyright License and Disclaimer are:
(i) works which incorporate all or portion of this document for the purpose of providing commentary or explanation (such as an annotated version of the document),
(ii) works which incorporate all or portion of this document for the purpose of incorporating features that provide accessibility,
(iii) translations of this document into languages other than English and into different formats and
(iv) works by making use of this specification in standard conformant products by implementing (e.g. by copy and paste wholly or partly) the functionality therein.
However, the content of this document itself may not be modified in any way, including by removing the copyright notice or references to Ecma International, except as required to translate it into languages other than English or into a different format.
The official version of an Ecma International document is the English language version on the Ecma International website. In the event of discrepancies between a translated version and the official version, the official version shall govern.
The limited permissions granted above are perpetual and will not be revoked by Ecma International or its successors or assigns.
This document and the information contained herein is provided on an “AS IS” basis and ECMA INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
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:
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.