Multipage preference

8 The TEA API

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

8.1 Security

Table 4: Security schemes
Scheme Type Description
bearerAuth http bearer

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

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

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

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

8.2 TEA Discovery

8.2.1 Resolve an identifier to TEA Product Releases

GET/discovery

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

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

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

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

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

Example request lines after serialization:

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.3 TEA Product

8.3.1 Query TEA Products

GET/products

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

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

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

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

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

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

sortField query No string (enum)

The field by which to sort the results.

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

One of: name. Default: "name".

sortOrder query No string (enum)

The direction of the sort.

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

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

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

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

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

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

error-response
403

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

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

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

8.3.2 Get a TEA Product

GET/product/{uuid}

Get a TEA Product by UUID

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.4 TEA Product Release

8.4.1 List the releases of a TEA Product

GET/product/{uuid}/releases

Get releases of the product

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

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

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

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

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

sortField query No string (enum)

The field by which to sort the results.

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

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

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

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

sortOrder query No string (enum)

The direction of the sort.

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

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.4.2 Query TEA Product Releases

GET/productReleases

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

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

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

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

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

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

sortField query No string (enum)

The field by which to sort the results.

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

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

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

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

sortOrder query No string (enum)

The direction of the sort.

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

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

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

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

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

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

error-response
403

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

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

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

8.4.3 Get a TEA Product Release with its latest collection

GET/productRelease/{uuid}

Get the TEA Product Release with its latest collection

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.5 TEA Component

8.5.1 Query TEA Components

GET/components

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

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

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

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

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

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

sortField query No string (enum)

The field by which to sort the results.

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

One of: name. Default: "name".

sortOrder query No string (enum)

The direction of the sort.

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

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

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

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

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

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

error-response
403

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

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

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

8.5.2 Get a TEA Component

GET/component/{uuid}

Get a TEA Component

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.6 TEA Component Release

8.6.1 List the releases of a TEA Component

GET/component/{uuid}/releases

Get releases of the component

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

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

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

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

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

sortField query No string (enum)

The field by which to sort the results.

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

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

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

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

sortOrder query No string (enum)

The direction of the sort.

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

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.6.2 Query TEA Component Releases

GET/componentReleases

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

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

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

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

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

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

sortField query No string (enum)

The field by which to sort the results.

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

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

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

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

sortOrder query No string (enum)

The direction of the sort.

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

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

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

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

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

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

error-response
403

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

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

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

8.6.3 Get a TEA Component Release with its latest collection

GET/componentRelease/{uuid}

Get the TEA Component Release with its latest collection

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.7 TEA Collection

8.7.1 List the collections of a TEA Product Release

GET/productRelease/{uuid}/collections

Get the TEA Collections belonging to the TEA Product Release

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

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

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

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

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

sortField query No string (enum)

The field by which to sort the results.

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

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

One of: version. Default: "version".

sortOrder query No string (enum)

The direction of the sort.

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

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.7.2 Get the latest collection of a TEA Product Release

GET/productRelease/{uuid}/collection/latest

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.7.3 Get one collection version of a TEA Product Release

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.7.4 List the collections of a TEA Component Release

GET/componentRelease/{uuid}/collections

Get the TEA Collections belonging to the TEA Component Release

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

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

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

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

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

sortField query No string (enum)

The field by which to sort the results.

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

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

One of: version. Default: "version".

sortOrder query No string (enum)

The direction of the sort.

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

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.7.5 Get the latest collection of a TEA Component Release

GET/componentRelease/{uuid}/collection/latest

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.7.6 Get one collection version of a TEA Component Release

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.8 TEA Artifact

8.8.1 Get the metadata of the latest TEA Artifact revision

GET/artifact/{uuid}/latest

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.8.2 Download the content of the latest TEA Artifact revision

GET/artifact/{uuid}/latest/download

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

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

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

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

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

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

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

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

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

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

string
302

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

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

error-response
406

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

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

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

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

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

200 Cache-Control string

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

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

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

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

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

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

8.8.3 Download the signature of the latest TEA Artifact revision

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

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

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

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

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

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

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

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

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

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

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

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

string
302

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

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

error-response
406

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

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

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

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

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

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

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

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

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

8.8.4 Get the metadata of one TEA Artifact revision

GET/artifact/{uuid}/{artifactVersion}

Get metadata for a specific revision of a specific TEA Artifact

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.8.5 Download the content of one TEA Artifact revision

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

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

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

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

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

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

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

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

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

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

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

The content of the requested TEA Artifact format.

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

string
302

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

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

error-response
406

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

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

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

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

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

200 Cache-Control string

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

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

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

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

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

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

8.8.6 Download the signature of one TEA Artifact revision

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

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

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

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

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

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

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

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

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

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

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

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

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

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

string
302

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

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

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

error-response
406

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

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

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

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

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

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

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

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

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

8.9 CLE

8.9.1 Get the lifecycle events of a TEA Product

GET/product/{uuid}/cle

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.9.2 Get the lifecycle events of a TEA Product Release

GET/productRelease/{uuid}/cle

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.9.3 Get the lifecycle events of a TEA Component

GET/component/{uuid}/cle

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.9.4 Get the lifecycle events of a TEA Component Release

GET/componentRelease/{uuid}/cle

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

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

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

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

error-response
403

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

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

error-response
404

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

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

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

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

8.10 TEA Authentication

8.10.1 Exchange credentials for a TEA access token

POST/token

Exchange credentials for a TEA access token.

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

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

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

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

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

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

Security: basicAuth or none (anonymous access)

Request body:

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

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

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

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

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

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