Setting up the API

Working with the Schematics API

Learn how to use the IBM Cloud® Schematics API using an Identity and Access Management token to authenticate.

To work with IBM Cloud Schematics API, you must provide an IBM Cloud® Identity and Access Management (IAM) token that is generated with your IBM Cloud credentials. Depending on the way you authenticate with IBM Cloud, you can choose between the following options to automate the creation of your IBM Cloud IAM token.

1. Create your IBM Cloud IAM access token.

The request body for your API token request depends on the IBM Cloud authentication method.

You can find the IBM Cloud IAM token in the access_token field of your API output. Note the IBM Cloud IAM token to retrieve additional header information in the next steps. sh {: codeblock} POST `https://iam.cloud.ibm.com/identity/token`

**Example output**

```text {: screen}
    {
    "access_token": "<iam_access_token>",
    "refresh_token": "<iam_refresh_token>",
    "uaa_token": "<uaa_token>",
    "uaa_refresh_token": "<uaa_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration": 1493747503
    "scope": "ibm openid"
    }
```

2. Retrieve the account ID of the of the token you are working with.

Replace <iam_access_token> with the IAM token retrieved from the access_token field of your API output in the previous step. In your API output, you can find the ID of your IBM Cloud account in the resources.metadata.guid field. sh {: codeblock} GET https://accounts.cloud.ibm.com/coe/v2/accounts | Input parameters | Values | | ---- | ---- | | Headers | :Content-Type: application/json:Authorization: bearer <iam_access_token>:Accept: application/json |

**Example output**

```text {: screen}
{
    "next_url": null,
    "total_results": 5,
    "resources": [
        {
            "metadata": {
                "guid": "<account_ID>",
                "url": "/coe/v2/accounts/<account_ID>",
                "created_at": "2020-09-29T02:49:41.842Z",
                "updated_at": "2020-08-16T18:56:00.442Z",
                "anonymousId": "1111a1aa1a1111a1aa11aa11111a1111"
            },
            "entity": {
                "name": "<account_name>",
            }
        }
      ]
}
```

3. Generate a new IBM Cloud IAM token that includes your IBM Cloud credentials and the account ID that you want to work with.

   If you use an IBM Cloud API key, you must use the IBM Cloud account ID the API key was created for. To access Schematics workspaces or actions in account B, log in to account B and create an IBM Cloud API key that is based on account B.

   POST https://iam.cloud.ibm.com/identity/token
   

   Input parameters to get IAM tokens.

   Input parameters	Values
   Header	:Content-Type: application/x-www-form-urlencoded:Authorization: Basic Yng6Yng=[^] Yng6Yng= equals the URL-encoded authorization for the username bx and the password bx.
   Body for IBM Cloud username and password	:grant_type: password:response_type: cloud_iam uaa:username: Your IBM Cloud username. :password: Your IBM Cloud password. :uaa_client_ID: cf:uaa_client_secret: Add the uaa_client_secret key with no value specified.:bss_account: The IBM Cloud account ID that you retrieved in the previous step.
   Body for IBM Cloud API keys	:grant_type: urn:ibm:params:oauth:grant-type:apikey:response_type: cloud_iam uaa:apikey: Your IBM Cloud API key.:uaa_client_ID: cf:uaa_client_secret: Add the uaa_client_secret key with no value specified.:bss_account: The IBM Cloud account ID that you retrieved in the previous step.
   Body for IBM Cloud one-time passcode	:grant_type:urn:ibm:params:oauth:grant-type:passcode:response_type: cloud_iam uaa:passcode: Your IBM Cloud passcode. :uaa_client_ID: cf:uaa_client_secret: Add the uaa_client_secret key with no value specified. :bss_account: The IBM Cloud account ID that you retrieved in the previous step.

   Example output

   {
       "access_token": "<iam_token>",
       "refresh_token": "<iam_refresh_token>",
       "token_type": "Bearer",
       "expires_in": 3600,
       "expiration": 1493747503
   }
   

   You can find the IBM Cloud IAM token in the access_token and the refresh token in the refresh_token field of your API output.

4. Use the Schematics API to list all the workspaces in your account.

   Syntax to list all workspaces

       GET https://schematics.cloud.ibm.com/v1/workspaces/ 
   

    | Input parameters | Values |
    | ----- |  --- |
    | Header | `Authorization: bearer <iam_token>`|
    {: caption="Input parameters to work with the IBM Cloud Schematics API." caption-side="top"}
   

   Syntax to retrieve information about a specific workspace:

   GET https://schematics.cloud.ibm.com/v1/workspaces/{id}
   

   Input parameters to work with the IBM Cloud Schematics API.

   Input parameters	Values
   Header	Authorization: bearer <iam_token>: your Your IBM Cloud IAM access token.
   Path	id <workspace_ID>: The ID of the workspace. To retrieve the workspace ID, run ibmcloud schematics workspace list

5. Review the IBM Cloud Schematics API documentation for a list of supported APIs.

Refreshing IBM Cloud IAM access tokens and obtaining new tokens with the API

An IBM Cloud® Identity and Access Management (IAM) access token expires after one hour. You must refresh your access token regularly to assure access to the IBM Cloud API. You can use the same steps to obtain a new token.

Before you begin, make sure that you have a valid IBM Cloud IAM refresh token or an IBM Cloud API key that you can use to request a new access token.

• Refresh token: Follow the instructions in Automating the workspace creation and management process with the IBM Cloud API.
• API key: Retrieve your IBM Cloud API key as follows.
  1. From the menu bar, click Manage > Access (IAM).
  2. Click the Users page and then select yourself.
  3. In the API keys pane, click Create an IBM Cloud API key.
  4. Enter a Name and Description for your API key and click Create.
  5. Click Show to see the API key that was generated for you.
  6. Copy the API key so that you can use it to retrieve your new IBM Cloud IAM access token.

Use the following steps if you want to create an IBM Cloud IAM token or if you want to obtain a new refresh token.

1. Generate a new IBM Cloud IAM access token by using the refresh token or the IBM Cloud API key.

   POST https://iam.cloud.ibm.com/identity/token
   

   Input parameters for a new IBM Cloud IAM token.

   Input parameters	Values
   Header	:Content-Type: application/x-www-form-urlencoded:Authorization: Basic Yng6Yng= Yng6Yng= equals the URL-encoded authorization for the username bx and the password bx.
   Body when using the refresh token	:grant_type: refresh_token:response_type: cloud_iam uaa:refresh_token: Your IBM Cloud IAM refresh token. :uaa_client_ID: cf:uaa_client_secret::bss_account: Your IBM Cloud account ID. Add the uaa_client_secret key with no value specified.
   Body when using the IBM Cloud API key	:grant_type: urn:ibm:params:oauth:grant-type:apikey:response_type: cloud_iam uaa:apikey: Your IBM Cloud API key. :uaa_client_ID: cf:uaa_client_secret: Add the uaa_client_secret key with no value specified.

   Example API output

   {
       "access_token": "<iam_token>",
       "refresh_token": "<iam_refresh_token>",
       "uaa_token": "<uaa_token>",
       "uaa_refresh_token": "<uaa_refresh_token>",
       "token_type": "Bearer",
       "expires_in": 3600,
       "expiration": 1493747503
   }
   

   You can find your new IBM Cloud IAM token in the access_token, and the refresh token in the refresh_token field of your API output.

2. Continue working with the IBM Cloud Schematics API documentation using the token from the previous step.