SBOM API Key Concepts

The following sections provide introduction to key concepts to help you get started with the SBOM Insights API.

API Refresh and Access Tokens

An API refresh token is a long-lived credential that a user generates to access the SBOM Insights public API (see Generating a Refresh Token). The refresh token is used to generate a short-lived access token that must be included in requests to the SBOM Insights API. Access tokens are most commonly generated using a command-line tool or SDK (see Generating an Access Token from a Refresh Token).

The long-lived refresh token credential is tied only to the user who generates it, and can be used only to make calls to an API that the user has access to. In the SBOM Insights user interface, access is defined by the roles that a user has been granted in an SBOM Insights Organization. If a user has been granted a role in more than one Organization, they can use the same refresh token to access resources in either Organization.

Refresh Token Notes

The following are key points about SBOM Insights API refresh tokens:

•

For security, an SBOM Insights API refresh token expires in one year if it is not used in that one year.

•

The refresh token will never expire if used at least once per year.

•

There is no limit on the number of active SBOM Insights API refresh tokens that a user may have.

•

Revoked refresh tokens cannot be used to generate new access tokens and can be discarded.

Access Token Notes

The following are key points regarding SBOM Insights API access tokens:

•

For security, access tokens are only valid for one hour.

•

After an access token expires, requests to the SBOM Insights API using that access token will no longer succeed.

•

To get a new access token, repeat the steps in the Generating an Access Token from a Refresh Token section.

API Refresh Token Security

Because refresh tokens are long-lived, the following security protocol should be followed:

•

Refresh tokens must be stored securely.

•

Tokens should never be shared with anyone else.

•

If a refresh token is compromised or lost, you should revoke the token immediately. For more information, refer to Revoking an API Refresh Token.

•

Any change to a user's roles will take effect immediately, affecting the access the user has, even if the user already has generated an API refresh token or access token.

•

Revoking an API refresh token does not invalidate access tokens that were generated with the refresh token.

Organization ID Unique Identifier

Each Organization in SBOM Insights is assigned an Organization ID. The Organization ID is a unique identifier that defines your Organization to SBOM Insights and is also used as part of the request path when consuming the API. After you log in to SBOM Insights, you will notice that your Organization ID is displayed in the URL as follows, where {orgID} is the unique identifier for your Organization:

https://sca-app.revenera.com/orgs/{orgID}/...

After you have generated your refresh token and then used it to obtain your access token, the specific URI for the API you want to invoke includes the Organization ID. For example, the following shows an example endpoint URI for the Create Bucket REST API:

https://sca-app.revenera.com/sbom/v1/orgs/{orgID}/buckets