---
name: transit-gateway-set-up-environment
title: Setting up your API environment
description: Before you can use the transit gateway API, you need to setup your environment.
last-updated: 2026-08-07
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/transit-gateway?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 environment
{: #set-up-environment}

Before you can use the transit gateway API, you need to setup your environment.
{: shortdesc}

## General prerequisites
{: #general-prerequisites}

Set up your account to access the transit gateway. Make sure that your account is [upgraded to a paid account](https://cloud.ibm.com/docs/account?topic=account-accountfaqs&format=markdown#changeacct).

## API prerequisites
{: #api-prerequisites-setup}

Before you can use the API to interact with a transit gateway, you must get an IAM token, store the endpoint as a variable, and verify that you have access to the IBM Cloud Transit Gateway API service.

The following examples use the `transit.cloud.ibm.com` global endpoint.
{: 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).

```sh
apikey="<YOUR_API_KEY>"
```
{: 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.

```sh
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 look similar to the following:
```text
Bearer <your token>
```
{: 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`.

Because the IAM token expires, you must repeat the preceding step to refresh your token every hour.
{: 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 that it can be reused later in your session.

Public endpoint:

```sh
transit_api_endpoint="https://transit.cloud.ibm.com"
```
{: pre}

Virtual private endpoint:

```sh
transit_api_endpoint="https://private.transit.cloud.ibm.com"
```
{: pre}

To verify that the variable was saved, run `echo $transit_api_endpoint` and ensure that the response is not empty.

### 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 that it can be reused in your session. For more information about setting the `version` parameter, see **Versioning** in the [Transit Gateway API](https://cloud.ibm.com/docs/apis/transit-gateway#api-versioning).

```sh
api_version="2020-03-31"
```
{: 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.
{: tip}

* Call the [List Available Locations API](https://cloud.ibm.com/docs/apis/transit-gateway#list-gateway-locations) to see the locations available for your transit gateway, in JSON format. At least one object returns.

    ```sh
    curl -X GET "$transit_api_endpoint/v1/offering_types/dedicated/locations?version=$api_version"   -H "Authorization: $IAM_TOKEN"
    ```
    {: pre}

* Call the [List gateways](https://cloud.ibm.com/docs/apis/transit-gateway#list-transit-gateways) API to see any gateways that you already created under your account, in JSON format.

    ```sh
    curl -X GET "$transit_api_endpoint/v1/transit_gateways?version=$api_version"   -H "Authorization: $IAM_TOKEN"
    ```
    {: pre}