Setting up your API and CLI environment

Before you can create an IBM Cloud® Virtual Private Cloud (VPC) by using the API or CLI, set up your environment.

General prerequisites

Set up your account to access VPC. Make sure that your account is upgraded to a paid account.
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:
```
ssh-keygen -t rsa
```
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.

CLI prerequisites

Before you can use the CLI to create your VPC, you must install the IBM Cloud CLI and the VPC CLI plug-in.

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.

Install the IBM Cloud CLI.
Install the VPC CLI plug-in.
```
ibmcloud plugin install vpc-infrastructure
```
The VPC CLI actions use the extension is. To learn how to use the CLI commands, you can run:
```
ibmcloud is help
ibmcloud is help vpc-create
ibmcloud is help instance-create
```
To learn how to create resources by using the CLI, see Creating VPC resources.

Accessing CLI through the VPC API private endpoint

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.

Ensure that the core IBM Cloud CLI and VPC infrastructure service plug-in are updated to the latest version:
```
ibmcloud update
ibmcloud plugin update vpc-infrastructure
```
To switch to API private endpoint mode, enter the following command:
```
ibmcloud login -a private.cloud.ibm.com
```
Currently, API private endpoint mode supports only us-south and us-east regions.

API prerequisites

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.

Step 1: Store your API key as a 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.

apikey="<YOUR_API_KEY>"

Step 2: Get an IBM Identity and Access Management (IAM) token

Run the following command to get and parse an IAM token by using the JSON processing utility jq. 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.

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)'`

To view the IAM token, run echo $iam_token. The result should look like this:

Bearer <your token>

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.

Step 3: Store the API endpoint as a variable

Run the following command to store the API endpoint in a variable so it can be reused later in your session.

Public endpoint:

vpc_api_endpoint="https://us-south.iaas.cloud.ibm.com"

Virtual private endpoint:

vpc_api_endpoint="https://us-south.private.iaas.cloud.ibm.com"

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.

Step 4: Store the API version as a 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.

api_version="2019-09-30"

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

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.

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.
```
curl -X GET "$vpc_api_endpoint/v1/regions?version=$api_version&generation=2" \
  -H "Authorization: $iam_token"
```

Call the GET Zones API to see all zones available for VPC in a particular region, such as us-south, in JSON format.

curl -X GET "$vpc_api_endpoint/v1/regions/us-south/zones?version=$api_version&generation=2" \
  -H "Authorization: $iam_token"

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.
```
curl -X GET "$vpc_api_endpoint/v1/instance/profiles?version=$api_version&generation=2" \
  -H "Authorization: $iam_token"
```
Call the GET Images API to return the images available for your instances, in JSON format. At least one object should return.
```
curl -X GET "$vpc_api_endpoint/v1/images?version=$api_version&generation=2" \
  -H "Authorization: $iam_token"
```

Call the GET VPCs API to see any VPCs that were already created under your account, in JSON format.

curl -X GET "$vpc_api_endpoint/v1/vpcs?version=$api_version&generation=2" \
  -H "Authorization: $iam_token"

To learn how to create resources by using the API, see Creating VPC resources with CLI and API.