Setting up the toolkit for V10 Reserved

Install the toolkit that provides CLI commands, and the API Designer user interface, for IBM® API Connect.

About this task

With the toolkit, you can choose how you want to work with your APIs:

API Designer offers a graphical interface similar to API Manager. Because you work locally, not all API Manager features are available in API Designer.
The CLI (Command Line Interface) lets you work in a command window instead of using the graphical interface.

Setting up the toolkit involves the following tasks:

Downloading the toolkit
Logging in to the toolkit with SSO (single sign-on)
Logging in to the toolkit with an IAM API key

Downloading the toolkit

About this task

To install the toolkit, download the compressed file that is appropriate for your chosen toolkit option and platform, then extract the contents to a chosen location on your local machine. The compressed file contains an executable file for running CLI commands and, if you choose the CLI + LoopBack + Designer option, an executable file for launching the API Designer application.

Procedure

Download the toolkit from API Manager in IBM API Connect Reserved on IBM Cloud.
1. Log in to IBM Cloud.
2. On the Dashboard, click > API Management > API Connect > Services.
3. In the list of services, expand the Reserved service and click a provider organization to open the IBM API Connect API Manager.
4. On the API Manager home page, click the Download Toolkit tile.
5. In the "Step 1: Download toolkit" section of the Install API Connect Toolkit window, select the type of package you want to download and click the link for your operating system.
  - CLI: provides a command line environment for working with IBM API Connect.
  - CLI + LoopBack + Designer: provides a command-line environment for working with IBM API Connect with LoopBack® support, plus the API Designer user interface.
Click the Download option for Credential and save the credentials.json file to your local file system.
In the "Step 3: Run commands" section, copy the IBM API Connect Management Server Endpoint URL.

You will use the URL every time you log in to the toolkit from the CLI, so save a copy where you can easily locate it.

You will run the commands from this section in the next steps, so you can close the Install API Connect Toolkit window.
Locate the downloaded toolkit compressed file and extract the contents to a folder of your choice.
The contents of the file depend on the your chosen toolkit option and platform, as follows:
- The apic-slim or apic-slim.exe file is the CLI for IBM API Connect.
- The apic or apic.exe file is the CLI for IBM API Connect including LoopBack support.
  Tip: If you are using the CLI option, then if you rename the apic-slim file to apic, or the apic-slim.exe file to apic.exe, you can run the CLI commands exactly as documented, copy and paste sample commands from the documentation, and use any command scripts as-is if you later move to the CLI + LoopBack + Designer option.
- The api_designer-platform file is the API Designer user interface application for the specified platform.
Optional: Delete the $HOME/.apiconnect/node_clis directory.

You need to do this only if you replaced a version of apic or apic.exe and are using the apic lb4 command. You need to delete the directory get apic to unpack the new loopback.

On Windows, $HOME is defined by environment USERPROFILE.
Run the CLI.
- For the Mac OSX or Linux® platforms, complete the following steps:
  1. Open a terminal instance and navigate to the folder where you extracted the contents of the toolkit compressed file.
  2. Make the CLI file an executable file by entering the following command:
```
chmod +x download_name
```
    Where download_name is the name of the toolkit file that you downloaded, either apic or apic-slim.
  3. Run CLI commands as follows:
```
./apic command_name_and_parameters
```
    or
```
./apic-slim command_name_and_parameters
```
    For details of the CLI commands, see toolkit CLI reference documentation.
- For the Windows platform, complete the following steps:
  1. Open a command prompt and navigate to the folder where you extracted the contents of the toolkit compressed file.
  2. Run CLI commands as follows:
```
apic command_name_and_parameters
```
    or
```
apic-slim command_name_and_parameters
```
    For details of the CLI commands, see toolkit CLI reference documentation.
Tip: Add the folder location of your CLI file to your PATH variable so that you can run CLI commands from anywhere in your file system.
Install the toolkit credentials by opening a terminal window (command window) and running the following command
```
apic client-creds:set toolkit_credentials_file_path/credentials.json
```
where credentials_file_path is the location where you downloaded the toolkit credentials JSON file. The toolkit uses these new credentials to authenticate with the management server. The response displays the Management Server Endpoint URL and the credentials file's name:

management-server-endpoint.cloud.ibm.com: credentials.json

Note: You can only install one set of toolkit credentials at a time. If you later want to log in to a different management server, install that server's toolkit credentials to replace the current credentials.

Logging in to the toolkit with SSO (single sign-on)

About this task

Log in to the IBM API Connect management server with the toolkit using SSO. Note that you can also log in by using an IAM API key; see Logging in to the toolkit with an IAM API key for details.

Procedure

Clear the toolkit credentials from any previous login by running the following command:
```
apic client-creds:clear
```
The response confirms that the credentials were deleted:
```
Deleted client credentials
```
Clearing the credentials ensures that you do not inadvertently log in with the wrong set of credentials (for example, from a different product release or environment).
Set the credentials that you want to use now by running the following command:
```
apic client-creds:set path_to_credentials/credential.json
```
where path_to_credentials is the location of the credential.json file that you want to use. For example:
```
apic client-creds:set /Users/local_user/credential.json
```
Log in by running the following command:
```
apic login --server mgmt_endpoint_url --sso
```
where mgmt_endpoint_url is the endpoint URL that you noted when you downloaded the toolkit.

When the toolkit prompts for the context, type provider and press Enter:

Context? provider

The server responds with the following message, which includes a lengthy URL:

Warning: Using default toolkit credentials.
Please copy and paste the url https://mgmt_endpoint_url/auth/manager/sign-in/?from=TOOLKIT to a browser to start the authentication process.
Do you want to open the url in default browser? [y/n]: y

Respond by typing y and pressing Enter.

The following message displays: API Key?

Then, the URL in the response is copied directly into the address bar of a new browser tab, and opens the IBM API Connect Reserved passcode page where you can obtain an API key:
Copy the provided passcode and paste it into the terminal (command window) at the API Key? prompt, and then press Enter.
If the response indicates an error, check for the following problems:
- You pasted the API key value more than 5 minutes after it was generated, so it expired.
  In this case, start the login process again and make sure to copy and paste the API key passcode within the 5-minute time limit.
- There's a problem with the toolkit credentials; for example, you did not download them or install them correctly.
  In this case, download and install the credentials again, then restart the login process.
When the API key is validated and you are successfully logged in to the toolkit, the following message displays:
```
Warning: Using default toolkit credentials.
Logged into mgmt_endpoint_url successfully
```
To log out of the toolkit, use the following command:
```
apic logout --server mgmt_endpoint_url
```
The response confirms your logout:
```
Successfully logged out of mgmt_endpoint_url
```

Logging in to the toolkit with an IAM API key

About this task

Procedure

Clear the toolkit credentials from any previous login by running the following command:
```
apic client-creds:clear
```
The response confirms that the credentials were deleted:
```
Deleted client credentials
```
Clearing the credentials ensures that you do not inadvertently log in with the wrong set of credentials (for example, from a different product release or environment). There is no need to clear the API Designer credentials.

apic iam-apikey --apiKey apikey --server mgmt_endpoint_url --tokenendpoint tokenendpoint

where

apikey is your API key for IBM Cloud.
mgmt_endpoint_url is the endpoint URL that you noted when you downloaded the toolkit.
tokenendpoint (optional) is the IAM server endpoint; the default endpoint is iam.cloud.ibm.com.

For example:

apic iam-apikey --apiKey f050b77-896c-4fb8-20f8-1234 --server test.com --tokenendpoint iam.cloud.ibm.com
Logged into test.com successfully

You can also log in interactively, as shown in the following example:

apic iam-apikey
Enter your IBM Cloud details
? Server: mgmnthost.com
? IBM Cloud API Key: apikey
Logged into mgmnthost.com successfully

To log out of the toolkit, use the following command:
```
apic logout --server mgmt_endpoint_url
```
The response confirms your logout:
```
Successfully logged out of mgmt_endpoint_url
```