HCP API Overview

This topic provides an overview for using HCP API, a RESTful API for managing platform resources.

Overview

The following steps describe the procedure for interacting with the HCP API:

1. Authenticate to HCP to generate an access token.
2. Use the access token to interact with your desired endpoints.

The HCP API uses the following URLs:

Prerequisites

You must have the following information to authenticate and interact with the API:

• Client ID: Service principal client ID used to authenticate to HCP. Refer to Create a service principal for instruction on getting the ID.
• Client secret: Service principal client secret used to authenticate to HCP. Refer to Create a service principal for instruction on getting the ID.
• Organization ID: HCP organization that contains the project of the resources you want to query. Refer to HCP Organizations for information about creating and managing organizations. You can retrieve your organization ID from the Organization settings page.
• Project ID: HCP project that contains the resources you want to query. Refer to HCP Projects for information about creating and managing projects. You can retrieve your project ID from the Project settings page.

Assign the IDs to the following variables:

• Set the HCP_CLIENT_ID and HCP_CLIENT_SECRET environment variables to a service principal key. Packer uses these values to authenticate to HCP and generate an access key.
• Set the ORGANIZATION_ID environment variable to your HCP organization ID.
• Set the PROJECT_ID environment variable to your HCP project ID.

Authenticate to HCP

The HCP API requires an access token to authorize the request.

Generate the access key with your HCP client ID and secret.

$ curl --location "https://auth.idp.hashicorp.com/oauth2/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=$HCP_CLIENT_ID" \
--data-urlencode "client_secret=$HCP_CLIENT_SECRET" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "audience=https://api.hashicorp.cloud"

In the following example response, the bearer access token is valid for one hour:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Set the HCP_ACCESS_TOKEN environment variable to the access token. This action makes it easier to reference the token when you are interacting with the API.

$ export HCP_ACCESS_TOKEN=<access-token>

Interact with API

After you have retrieved the access token, you are now ready to use the HCP API. You need to provide the access token in the Authorization header as a bearer token in each request.

The following example shows you how to retrieve HCP Packer buckets in your HCP project. The workflow and authorization process is similar for other HCP operations.

$ curl --location "https://api.cloud.hashicorp.com/packer/2021-04-30/organizations/$ORGANIZATION_ID/projects/$PROJECT_ID/images?pagination.page_size=10" \
--header "authorization: Bearer $HCP_ACCESS_TOKEN"

Refer to the API documentation of the specific service owning resources for more information.

Versioning

Versions are specific per service owning resources. Version names format is YYYY-MM-DD, for example, 2021-04-30.