Managing resources with the App Connect API

You can use the App Connect API to manage your resources after you obtain an access token for authentication.

About this task

You can use the App Connect API to provide access to resources in your instance so that you can administer BAR files, configurations, integration runtimes, and trace. For more information, see API overview.

To use the App Connect API, you must first authenticate your credentials by including an access token in your API calls. To get an access token, you must generate an API key, a client ID, and a secret in App Connect. The client ID represents a specific instance of App Connect and all users of that instance share the ID. The API key represents a specific user of an instance and is specific to that user.

If you have a service that needs to access the API, you can also create a service ID, then create an API key for the service ID. The service ID is a type of user ID that represents that service. All users of the instance where the service ID is created can access the service ID.

Accessing the API with a personal API key

Procedure

The following steps describe how a specific user can get an access token by generating an API key, client ID, and secret.

Log in to your instance of App Connect.
Generate an API key by completing the following steps.
1. Click your initials on the App Connect header, then select Service IDs and API keys.
2. Click the API keys tab, then click Generate key.
3. Enter a name for your API key, add a description if you want one, then click Generate key.
  The name of the API key can be up to 32 characters long and can contain alphanumeric characters, underscores (_), hyphens (-), and periods (.).
  An API key is generated and is visible for 300 seconds. You can view the key by clicking (Show API key). You can't recover the API key after you leave this screen. Therefore, either download it as a JSON file by clicking the provided link, or click Copy to clipboard, then paste the key into a file for later use. After you download or copy the key, close the dialog box.
Generate a client ID and secret by completing the following steps.
1. Expand the Connect category in the navigation pane, then click Public API credentials.
2. On the Public API credentials page, click Generate.
3. Enter a name for your client ID, then click Generate.
  The name of the client ID can be up to 40 characters long and can contain alphanumeric characters, underscores (_), and hyphens (-).
  A client ID and secret are generated. You can't recover the client secret after you leave this screen. Copy the values by clicking Copy to clipboard , then paste them into a file for later use. After you copy the values, click Close.
4. Optional: To download the OpenAPI specification for this API, click API specification.
To get an access token, use a tool like cURL to send a POST request to the App Connect API for the token object (api/v1/tokens).
You need to provide the following information.
- The URL of the API for your App Connect instance, which is https://api.region.appconnect.ipaas.automation.ibm.com, where region is the region where your instance is hosted. You can find the region (such as a-vir-c1) in the URL for your instance.
  You can also generate this URL in the API specification by selecting the server and region. The server for the App Connect capability of IBM® webMethods Hybrid Integration is https://api.region.appconnect.ipaas.automation.ibm.com.
- The instance ID of your App Connect instance, which is the nine-character identifier at the beginning of the URL for your instance.
- The API key, client ID, and client secret that you generated.
The following example shows the structure of the cURL command that you would use with your credentials to get an access token.
```
curl --request POST \
  --url https://api.region.appconnect.ipaas.automation.ibm.com/api/v1/tokens \
  --header 'X-IBM-Client-Id: clientId' \
  --header 'X-IBM-Client-Secret: clientSecret' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-ibm-instance-id: appConnectInstanceId' \
  --data '{
  "apiKey": "myapikey"
}'
```

Results

If your request is successful and your credentials are confirmed, an access token is returned in the following format.

{
    "access_token": "myAccessToken",
    "token_type": "bearer",
    "scope": "appcon:manage",
    "expires_in": 43200
}

Note: The access token is valid for 12 hours from when it is created. After that time, you must request a new token.

When you make subsequent calls to the API, you must use the X-IBM-Client-Id header to provide your client ID, and the

Authorization:
Bearer

header to provide this access token. For example, the following call requests a list of configurations.

curl --request GET \
--url https://api.region.appconnect.ipaas.automation.ibm.com/api/v1/configurations \
--header "Authorization: Bearer myAccessToken" \
--header 'X-IBM-Client-Id: myClientId' \
--header 'accept: application/json'

Note: Authorization: Bearer is case-sensitive and must be referred to in calls with the correct capitalization.

Accessing the API with a shared service ID