*This page
applies to **Apigee** and **Apigee hybrid**.*

This page explains how to provision API hub from the command line. To
provision API hub using the wizard-style UI, see [Provision API hub in the Cloud console](https://docs.cloud.google.com/apigee/docs/apihub/provision.md.txt). To provision API hub using a Terraform configuration, see [Provision API hub using Terraform](https://docs.cloud.google.com/apigee/docs/apihub/provision-terraform.md.txt).

## Before you begin

1.

   Make sure that you have the following role or roles on the project:

   - `roles/serviceusage.serviceUsageAdmin`
   - `roles/serviceusage.serviceUsageViewer`
   - `roles/cloudkms.admin`
   - `roles/apihub.provisioningAdmin`
   - `roles/resourcemanager.projectIamAdmin`

   <br />

   #### Check for the roles

   1.
      In the Google Cloud console, go to the **IAM** page.

      [Go to IAM](https://console.cloud.google.com/projectselector/iam-admin/iam?supportedpurview=project)
   2. Select the project.
   3.
      In the **Principal** column, find all rows that identify you or a group that
      you're included in. To learn which groups you're included in, contact your
      administrator.

   4. For all rows that specify or include you, check the **Role** column to see whether the list of roles includes the required roles.

   #### Grant the roles

   1.
      In the Google Cloud console, go to the **IAM** page.

      [Go to IAM](https://console.cloud.google.com/projectselector/iam-admin/iam?supportedpurview=project)
   2. Select the project.
   3. Click **Grant access**.
   4.
      In the **New principals** field, enter your user identifier.

      This is typically the email address for a Google Account.

   5. Click **Select a role**, then search for the role.
   6. To grant additional roles, click **Add
      another role** and add each additional role.
   7. Click **Save**.
2. Ensure that your Google Cloud project doesn't have the `Google Cloud Platform - Resource Location Restriction` [organization policy constraint](https://docs.cloud.google.com/resource-manager/docs/organization-policy/using-constraints) added. **Important:** API hub uses Cloud Scheduler for some of its features. Cloud Scheduler is not available in all Google Cloud locations. If you are provisioning API hub in a location where Cloud Scheduler is not available, it will be provisioned in a fallback location. For a list of these locations and their fallbacks, see [API hub locations](https://docs.cloud.google.com/apigee/docs/apihub/locations.md.txt). If your organization has a `Resource Location Restriction` policy that prevents resources from being created in the fallback location, provisioning will fail.
3. Optional: [Configure VPC Service Controls](https://docs.cloud.google.com/apigee/docs/apihub/vpc-service-control.md.txt).

## Summary of steps

The provisioning steps are as follows:

- [Step 1: Enable APIs](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#step-apis). You must enable a set of Google Cloud APIs for Apigee API hub to operate.
- [Step 2: Create the Apigee API hub service identity](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#step-service-identity). The service identity allows the API hub instance to call the Google Cloud APIs it requires to perform its operations.
- [Step 3. Grant the roles and permissions to the default service account](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#step-permissions).
- [Step 4. Configure encryption](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#step-encryption). You can choose whether to use a Google-owned and Google-managed encryption key (GMEK) or Customer-managed encryption key (CMEK) approach to encrypt and decrypt your API data at rest. See [Comparison of CMEK and Google-owned and Google-owned and Google-managed encryption keys](https://docs.cloud.google.com/kms/docs/cmek.md.txt).
- [Step 5: Create the API hub instance.](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#step-hosting) To finish up, you must register the host project and create the API hub instance.

> [!NOTE]
> **Note:** If you haven't already provisioned Apigee in your project, API hub provisioning also creates an Apigee organization in your project.

## Provisioning steps

Ensure that you have met the prerequisites described in
[Before you begin](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#before-you-begin).

> [!CAUTION]
> **Caution:** If you have recently deprovisioned API hub, you must wait **7 days** before provisioning a new instance in the same Google Cloud project. This is because deprovisioning moves the associated Apigee organization (if any) to a soft-delete state for **7 days**, and API hub can only be reprovisioned after the Apigee org is permanently deleted.

### Step 1: Enable APIs

To provision API hub, you must enable the following
APIs in your Google Cloud project:

#### Permissions required for this task

You can give the Apigee API hub provisioner a predefined role that includes the
permissions needed to complete this task, or give more fine-grained
permissions to provide the least privilege necessary. See
[Predefined roles](https://docs.cloud.google.com/apigee/docs/api-platform/get-started/permissions.md.txt#predefined-roles) and
[API enablement permissions](https://docs.cloud.google.com/apigee/docs/api-platform/get-started/permissions.md.txt#api-enablement-permissions).

1. Enable the required Google Cloud APIs by executing the following [`services enable`](https://docs.cloud.google.com/sdk/gcloud/reference/services/enable)
   command:

   ```
   gcloud services enable apihub.googleapis.com \
       cloudkms.googleapis.com --project=YOUR_PROJECT_ID
   ```

   Where <var translate="no">`YOUR_PROJECT_ID`</var> is the Cloud project ID that you created
   in [Before you begin](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#before-you-begin).

   **Important:** Enabling the API hub API also automatically enables the Apigee API (`apigee.googleapis.com`) for your Google Cloud project. This applies to all projects, regardless of whether Apigee has been provisioned or if the Apigee API was previously disabled.


   Note that API hub remains a free service. Auto-enablement of the Apigee API during the API hub provisioning process has no pricing or billing implications for your project.

### Step 2: Create the Apigee API hub service identity

The [service identity](https://docs.cloud.google.com/run/docs/securing/service-identity.md.txt) allows the
API hub instance to call the Google Cloud APIs it
requires to perform its operations.

1. Create the service identity:

   ```
   gcloud beta services identity create --service=apihub.googleapis.com \
     --project=YOUR_PROJECT_ID
   ```

   Where <var translate="no">`YOUR_PROJECT_ID`</var> is the Cloud project ID that you created
   in [Before you begin](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#before-you-begin).
2. Verify that the agent was successfully created. The response includes the name of
   the agent in the following format:
   `service-PROJECT_NUMBER@gcp-sa-apihub.iam.gserviceaccount.com`.
   For example:

   ```
   Service identity created: service-1234567890@gcp-sa-apihub.iam.gserviceaccount.com
   ```

   Note that you will need to use this service identity in a later step.

### Step 3: Grant the roles and permissions to the default service account

In this step, you grant the `apihub.admin` and `apihub.runtimeProjectServiceAgent` roles to the API hub default service account. These permissions are required to use [API hub plugins](https://docs.cloud.google.com/apigee/docs/apihub/plugins.md.txt).

```
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCOUNT \
  --role="roles/apihub.admin"
    
```

```
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCOUNT \
  --role="roles/apihub.runtimeProjectServiceAgent"
    
```

Where:

- <var translate="no">`YOUR_PROJECT_ID`</var>: The Cloud project ID that you created in [Before you begin](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#before-you-begin).
- <var translate="no">`SERVICE_ACCOUNT`</var>: The ID of the service account you created in [Step 2](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#step-service-identity). The ID will look something like this: `service-1234567890@gcp-sa-apihub.iam.gserviceaccount.com`.

### Step 4: Configure encryption

In this step, you configure how the encryption of data in your API hub instance is
managed. You can use a Google-owned and Google-managed encryption key (GMEK) or create your own customer-managed
encryption key (CMEK). See [Comparison of CMEK and Google-owned and Google-owned and Google-managed encryption keys](https://docs.cloud.google.com/kms/docs/cmek.md.txt).

> [!CAUTION]
> **Caution:** If you use CMEK to encrypt your API hub data, ensure the key remains enabled and available. If the key is disabled or becomes unavailable for more than **7 days**, all data in your API hub instance will be permanently deleted and the instance will enter an unrecoverable state.

### CMEK steps

Follow these steps if you wish to use CMEK for data encryption:

1. Create a runtime database encryption key ring and key. You can use an existing CMEK key and key ring if you wish. Note that the
   key must be created in the same location where you plan to create the API hub instance.

   1. Create a new key ring:

      The key ring's name must be unique to your organization. If you create a
      second or subsequent region, the name cannot be the same as any other key ring.

      ```
      gcloud kms keyrings create KEY_RING_NAME \
        --location KEY_RING_LOCATION --project YOUR_PROJECT_ID
      ```

      Where:
      - <var translate="no">`KEY_RING_NAME`</var>: The name of the key ring to create.
      - <var translate="no">`KEY_RING_LOCATION`</var>: The physical location of the key ring. This location must be the same as you plan to use for the API hub instance you will create in a later step. For the list of available locations, see [API hub locations](https://docs.cloud.google.com/apigee/docs/apihub/locations.md.txt).
      - <var translate="no">`YOUR_PROJECT_ID`</var>: The Cloud project ID that you created in [Before you begin](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#before-you-begin).
   2. Create the encryption key and add it to the key ring:

      ```
      gcloud kms keys create KEY_NAME \
        --keyring KEY_RING_NAME \
        --location KEY_LOCATION \
        --purpose "encryption" \
        --project YOUR_PROJECT_ID
      ```

      Where:
      - <var translate="no">`KEY_NAME`</var>: The name of the database key you are creating.
      - <var translate="no">`KEY_RING_NAME`</var>: The name of the key ring you just created.
      - <var translate="no">`KEY_LOCATION`</var>: The physical location of the key. Use the same location you used to create the key ring.

        <br />

   3. Get the key ID:

      ```
      gcloud kms keys list \
        --location=KEY_LOCATION \
        --keyring=KEY_RING_NAME \
        --project=YOUR_PROJECT_ID
      ```

      The key ID has the following syntax (similar to a file path). Retain this
      key ID, as you will need to use it in a later step:

      ```
      projects/YOUR_PROJECT_ID/locations/KEY_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME
      ```
   4. Grant access for the Apigee Service Agent to use the new key:

      ```
      gcloud kms keys add-iam-policy-binding KEY_NAME \
        --location KEY_LOCATION \
        --keyring KEY_RING_NAME \
        --member serviceAccount:SERVICE_ACCOUNT \
        --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
        --project YOUR_PROJECT_ID
      ```

      Where: <var translate="no">SERVICE_ACCOUNT</var> is the ID of the service account you created in
      Step 2. The ID will look something like this: `service-1234567890@gcp-sa-apihub.iam.gserviceaccount.com`.

      This command binds the key to the Apigee API hub Service Agent.

      On successful completion of this request, `gcloud` responds with
      something similar to the following:

      ```
      Updated IAM policy for key [runtime].
      bindings:
      - members:
        - serviceAccount:service-1234567890@gcp-sa-apihub.iam.gserviceaccount.com
        role: roles/cloudkms.cryptoKeyEncrypterDecrypter
      etag: BwWqgEuCuwk=
      version: 1
      ```

      If you get an error like the following:

      ```
      INVALID_ARGUMENT: Role roles/cloudkms.cryptokms.cryptoKeyEncrypterDecrypter is not supported for this resource.
      ```

      Be sure that you used the project *number* and not the project name in the
      service account email address.

### GMEK steps

If you wish to use GMEK for data encryption, go to the next step, [Step 5: Create the API hub instance](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#step-hosting), now.
No further key configuration is required.

### Step 5: Create the API hub instance

A *host project* is the Google Cloud project in which you will provision Apigee API hub.
You can provision only one API hub instance per host project.

<br />

1. Register the host project:

   ```
   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" -d '{
     "gcpProject": "projects/YOUR_PROJECT_ID"
     }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/hostProjectRegistrations?host_project_registration_id=HOST_ID
   ```

   Where:
   - <var translate="no">`YOUR_PROJECT_ID`</var>: The Cloud project ID that you created in [Before you begin](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#before-you-begin).
   - <var translate="no">`PROJECT_LOCATION`</var>: The physical location (region) where you'd like to host your Apigee API hub instance. You must use the same location you used to create the CMEK key and key ring. For the list of available locations, see [API hub locations](https://docs.cloud.google.com/apigee/docs/apihub/locations.md.txt).
   - <var translate="no">`HOST_ID`</var>: The name of your Google Cloud project where you'd like to provision Apigee API hub.
2. Create the API hub instance:

   ### With CMEK

   If you used CMEK for data encryption, execute the following command:

   ```
   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" -d '{
     "config":{
       "cmekKeyName":"KEY_NAME",
       "vertexLocation":"VERTEX_LOCATION",
       "disableSearch":false,
       "encryptionType":"CMEK"
       }
     }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/apiHubInstances?api_hub_instance_id=INSTANCE_ID
   ```

   Where:
   - `KEY_NAME` (Required): The fully qualified name of the CMEK key. This name was returned when the key was created. For example: `projects/YOUR_PROJECT_ID/locations/HOST_LOCATION/hostProjectRegistrations/HOST_ID`.
   - <var translate="no">`VERTEX_LOCATION`</var> (Optional): Specifies the [multi-region location](https://docs.cloud.google.com/generative-ai-app-builder/docs/locations.md.txt) in which to store your Vertex AI-based search data, the data associated with the [Semantic Search](https://docs.cloud.google.com/apigee/docs/apihub/search-apis.md.txt#semantic-search) feature of API hub. You can use either `us` or `eu` for this value. **Note:** If you don't specify a location for Vertex AI-based search data, omit this parameter and set the `disableSearch` parameter to `true`.
   - `encryptionType` (Required) You must use `CMEK`.
   - <var translate="no">`YOUR_PROJECT_ID`</var> is the Cloud project ID that you created in [Before you begin](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#before-you-begin).
   - <var translate="no">`PROJECT_LOCATION`</var>: You must use the same location you used to register the host project.
   - <var translate="no">`INSTANCE_ID`</var>: The name of the API hub instance. This value should be 4-40 characters, and valid characters are `/[a-z][A-Z][0-9]-_/`.

   ### With GMEK

   If you are using GMEK for data encryption, execute the following command:

   ```
   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" -d '{
     "config":{
       "vertexLocation":"VERTEX_LOCATION",
       "disableSearch":false,
       "encryptionType":"GMEK"
       }
     }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/apiHubInstances?api_hub_instance_id=INSTANCE_ID
   ```

   Where:
   - <var translate="no">`VERTEX_LOCATION`</var> (Optional): Specifies the [multi-region location](https://docs.cloud.google.com/generative-ai-app-builder/docs/locations.md.txt) in which to store your Vertex AI-based search data, the data associated with the [Semantic Search](https://docs.cloud.google.com/apigee/docs/apihub/search-apis.md.txt#semantic-search) feature of API hub. You can use either `us` or `eu` for this value. **Note:** If you don't specify a location for Vertex AI-based search data, omit this parameter and set the `disableSearch` parameter to `true`.
   - `encryptionType` must be `GMEK`. If you do not provide an encryption type, GMEK is the default.
   - <var translate="no">`YOUR_PROJECT_ID`</var> is the Cloud project ID that you created in [Before you begin](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#before-you-begin).
   - <var translate="no">`PROJECT_LOCATION`</var>: You must use the same location you used to register the host project.
   - <var translate="no">`INSTANCE_ID`</var>: The name of the API hub instance. This value should be 4-40 characters, and valid characters are `/[a-z][A-Z][0-9]-_/`.

### Step 5: (Optional) Create a runtime project attachment

3. If you provisioned API hub in a project that has Apigee proxies, perform this optional step to automatically register the proxies in API hub.

```
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" \
  -d '{
    "runtimeProject": "projects/YOUR_PROJECT_ID"
  }' \
  "https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/runtimeProjectAttachments?runtimeProjectAttachmentId=YOUR_PROJECT_ID"
  
```
4. Where:
   - <var translate="no">`YOUR_PROJECT_ID`</var> is the Cloud project ID that you created in [Before you begin](https://docs.cloud.google.com/apigee/docs/apihub/provision-cli.md.txt#before-you-begin).
   - <var translate="no">`PROJECT_LOCATION`</var>: You must use the same location you used to register the host project.

## Considerations

5. If you have recently deprovisioned API hub, you must wait **7 days** before provisioning a new instance in the same Google Cloud project. This is because deprovisioning moves the associated Apigee organization (if any) to a soft-delete state for **7 days**, and API hub can only be reprovisioned after the Apigee org is permanently deleted.

## What's next

6. Now, you are ready to begin using API hub:
   - Learn about the [Get started with API hub](https://docs.cloud.google.com/apigee/docs/apihub/getting-started-apihub.md.txt) page.
   - Review the [roles and permissions](https://docs.cloud.google.com/apigee/docs/apihub/iam-roles.md.txt) required to use API hub
   - Configure API hub attributes:
     - [Manage attributes](https://docs.cloud.google.com/apigee/docs/apihub/manage-attributes.md.txt)
     - [Quickstart: Create and edit attributes](https://docs.cloud.google.com/apigee/docs/apihub/quickstart-settings.md.txt)
   - Register an API resource:
     - [Manage API resources](https://docs.cloud.google.com/apigee/docs/apihub/manage-apis.md.txt)
     - [Quickstart: Register an API](https://docs.cloud.google.com/apigee/docs/apihub/quickstart-api.md.txt)
   - Add an API version:
     - [Versions overview](https://docs.cloud.google.com/apigee/docs/apihub/versions-intro.md.txt)
     - [Quickstart: Create an API version](https://docs.cloud.google.com/apigee/docs/apihub/quickstart-version.md.txt)