--- name: vpc-set-up-environment title: Setting up your API and CLI environment description: Before you can create an IBM Cloud® Virtual Private Cloud (VPC) by using the API or CLI, set up your environment. last-updated: 2026-06-26 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/vpc?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Setting up your API and CLI environment {: #set-up-environment} Before you can create an IBM Cloud® Virtual Private Cloud (VPC) by using the API or CLI, set up your environment. {: shortdesc} ## General prerequisites {: #general-prerequisites} 1. Set up your account to access VPC. Make sure that your account is [upgraded to a paid account](https://cloud.ibm.com/docs/account?topic=account-accountfaqs&format=markdown#changeacct){: external}. 2. Make sure that you have a public SSH key, which will be used to connect to the virtual server instance. For example, generate an SSH key on your Linux server by running the following command: ```sh ssh-keygen -t rsa ``` {: pre} This command generates two files. The generated public key is in the `id_rsa.pub` file under an ``.ssh`` directory in your home directory, for example, ``.../.ssh/id_rsa.pub``. For more information, see [SSH keys](https://cloud.ibm.com/docs/vpc?topic=vpc-ssh-keys&format=markdown). ## CLI prerequisites {: #cli-prerequisites-setup} {: cli} Before you can use the CLI to create your VPC, you must install the IBM Cloud CLI and the VPC CLI plug-in. [Deprecated]{: tag-deprecated} IBM Cloud CLI is not supported on LinuxONE (s390x processor architecture). However, you can install the CLI on another supported platform and use it with LinuxONE (s390x processor architecture) virtual server instances. {: note} 1. Install the [IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cli-getting-started&format=markdown){: external}. 1. Install the VPC CLI plug-in. ```sh ibmcloud plugin install vpc-infrastructure ``` {: pre} The VPC CLI actions use the extension `is`. To learn how to use the CLI commands, you can run: ```sh ibmcloud is help ibmcloud is help vpc-create ibmcloud is help instance-create ``` {: pre} To learn how to create resources by using the CLI, see [Creating VPC resources](https://cloud.ibm.com/docs/vpc?topic=vpc-creating-vpc-resources-with-cli-and-api&interface=cli&format=markdown). ### Accessing CLI through the VPC API private endpoint {: #access_cli_through_api_private_endpoints} To set the CLI to use the VPC API private endpoint, follow these steps: If you need to download the IBM Cloud CLI and associated plug-ins, you must be able to access the public repository where they are located. {: note} 1. Ensure that the core IBM Cloud CLI and VPC infrastructure service plug-in are updated to the latest version: ```sh ibmcloud update ibmcloud plugin update vpc-infrastructure ``` {: pre} 1. To switch to API private endpoint mode, enter the following command: ```sh ibmcloud login -a private.cloud.ibm.com ``` {: pre} Currently, API private endpoint mode supports only `us-south` and `us-east` regions. {: important} ## API prerequisites {: #api-prerequisites-setup} {: api} Before you can use the API to create your VPC, you must get an IAM token, store the endpoint as a variable, and verify that you have access to the VPC API service. The following examples use the `us-south` regional endpoint. To view additional API endpoints, see [Virtual Private Cloud API](https://cloud.ibm.com/docs/apis/vpc/latest#endpoint-url). {: note} ### Step 1: Store your API key as a variable {: #store-api-key-variable} Run the following command to store the API key for your account in an environment variable. If you don't have an API key, see [Creating an API key](https://cloud.ibm.com/docs/iam?topic=iam-userapikey&interface=ui&format=markdown#create_user_key){: external}. ```bash apikey="" ``` {: pre} ### Step 2: Get an IBM Identity and Access Management (IAM) token {: #get-iam-token} Run the following command to get and parse an IAM token by using the JSON processing utility [jq](https://stedolan.github.io/jq/){: external}. You can modify the command to use another parsing tool, or you can remove the last part of the command if you prefer to manually parse the token. ```json iam_token=`curl -k -X POST \ --header "Content-Type: application/x-www-form-urlencoded" \ --header "Accept: application/json" \ --data-urlencode "grant_type=urn:ibm:params:oauth:grant-type:apikey" \ --data-urlencode "apikey=$apikey" \ "https://iam.cloud.ibm.com/identity/token" |jq -r '(.token_type + " " + .access_token)'` ``` {: pre} To view the IAM token, run ``echo $iam_token``. The result should look like this: ```sh Bearer ``` {: screen} The Authorization header expects the token to begin with "Bearer". If the result doesn't include "Bearer", update the `iam_token` variable to include it. These examples assume that "Bearer" is included in the `iam_token`. You must repeat the preceding step to refresh your IAM token every hour because the token expires. {: important} ### Step 3: Store the API endpoint as a variable {: #store-api-endpoint-variable} Run the following command to store the API endpoint in a variable so it can be reused later in your session. Public endpoint: ```sh vpc_api_endpoint="https://us-south.iaas.cloud.ibm.com" ``` {: pre} Virtual private endpoint: ```sh vpc_api_endpoint="https://us-south.private.iaas.cloud.ibm.com" ``` {: pre} To verify that this variable was saved, run ``echo $vpc_api_endpoint`` and make sure that the response is not empty. For supported endpoint regions, see [Endpoints available](https://cloud.ibm.com/docs/vpc?topic=vpc-service-endpoints-for-vpc&format=markdown). {: note} ### Step 4: Store the API version as a variable {: #store-api-version-variable} Every API request must include the `version` parameter, in the format `YYYY-MM-DD`. Run the following command to store the version date in a variable so it can be reused in your session. For more information about setting the `version` parameter, see **Versioning** in the [Virtual Private Cloud API](https://cloud.ibm.com/docs/apis/vpc/latest#api-versioning). ```sh api_version="2019-09-30" ``` {: pre} To verify that this variable was saved, run ``echo $api_version`` and make sure that the response is not empty. ### Step 5: Verify that you have API access {: #verify-api-access} If you run into unexpected results, add the `--verbose` (debug) flag after the `curl` command to obtain detailed logging information. For more information about commonly encountered errors, see [Troubleshooting](https://cloud.ibm.com/docs/vpc?topic=vpc-troubleshooting-vpc&format=markdown). {: tip} * Call the GET Regions API to see the regions available for VPC, in JSON format. At least one object should return. You must send the `generation` parameter with every API request to specify which generation to use. For generation 2 virtual server instances, specify `generation=2`. For more information, see **Generation** in the [Virtual Private Cloud API](https://cloud.ibm.com/docs/apis/vpc/latest#api-generation-parameter). {: important} ```sh curl -X GET "$vpc_api_endpoint/v1/regions?version=$api_version&generation=2" \ -H "Authorization: Bearer $iam_token" ``` {: pre} * Call the GET Zones API to see all zones available for VPC in a particular region, such as `us-south`, in JSON format. ```curl curl -X GET "$vpc_api_endpoint/v1/regions/us-south/zones?version=$api_version&generation=2" \ -H "Authorization: Bearer $iam_token" ``` {: pre} * Call the GET Profiles API to see the profiles available for your virtual server instances, in JSON format. At least one object should return. Add ` | json_pp ` after the curl command to get a readable JSON string. The `json_pp` command is a JSON preprocessor that is typically installed by default on most Linux distributions. {: tip} ```curl curl -X GET "$vpc_api_endpoint/v1/instance/profiles?version=$api_version&generation=2" \ -H "Authorization: Bearer $iam_token" ``` {: pre} * Call the GET Images API to return the images available for your instances, in JSON format. At least one object should return. ```curl curl -X GET "$vpc_api_endpoint/v1/images?version=$api_version&generation=2" \ -H "Authorization: Bearer $iam_token" ``` {: pre} * Call the GET VPCs API to see any VPCs that were already created under your account, in JSON format. ```curl curl -X GET "$vpc_api_endpoint/v1/vpcs?version=$api_version&generation=2" \ -H "Authorization: Bearer $iam_token" ``` {: pre} To learn how to create resources by using the API, see [Creating VPC resources with CLI and API](https://cloud.ibm.com/docs/vpc?topic=vpc-creating-vpc-resources-with-cli-and-api&interface=cli&format=markdown).