Introduction

IBM® Blockchain Platform provides a managed and full stack blockchain-as-a-service (BaaS) offering. It simplifies your journey to build a Hyperledger Fabric based blockchain network and allows you to deploy blockchain components in environments of your choice.

These APIs are for provisioning Fabric components and administering the IBM Blockchain Platform console. They do not include Fabric operations.

- Use Fabric CA APIs to perform CA operations such as registering or enrolling users.
- Use Fabric SDKs or Peer CLI commands to perform other Fabric operations.

Updates

  • v2 APIs
    • New IBM Blockchain Platform console APIs using the route /v2/ are now available. Use of the earlier /v1/ APIs continues to be supported.
  • Configuration override
    • The IBM® Blockchain Platform APIs have been updated to allow you to customize the deployment of your component. The Fabric Certificate authority (CA), peer, and ordering node configuration files can now be customized by sending a configuration override in JSON. For more information, see Configuration Override.

Authentication (IBM Cloud only)

  • If you are looking for instructions on using the APIs with the IBM Blockchain Platform v2.1.x on the OpenShift Container Platform, Kubernetes, or IBM Cloud Private refer to these instructions for authentication.

Introduction

To authenticate an API request, you need to provide an access/bearer token in the request. To do that we first need to create a service credential, then exchange the API key from the service credential for an access/bearer token. Finally, construct the authorization header with the access/bearer token.

Gather the following information:

  • API Key and API Endpoint

    The (IAM) API key is used to authenticate your requests to your IBM Blockchain Platform service instance. The API endpoint is the url that allows you to access your service instance.

    You can get the API key and API endpoint by creating a new service credential for your service instance:

    1. In your IBM Cloud dashboard, open the IBM Blockchain Platform service instance that you created.
    2. Click Service credentials from the left navigator.
    3. Click the "New Credential" button on the Service credentials page to create a new credential.
      1. Give the credential a Name to remember its purpose. Example, Test Service Credential.
      2. Select a permission (Manager, Writer, or Reader) from the Role drop-down. For more information about each role, see the table in Add and remove users from the console.
      3. Ignore the optional Select Service ID drop-down.
      4. Ignore the optional Inline configuration Parameters text-area.
      5. Click the Add button.
    4. After the new credential is created, click View credentials under the Actions table header. The field api_endpoint value is your API endpoint and the apikey value is your API key.
      • API Key - The IAM API key is a secret/password that does not expire. Keep this key in a secure location. You will use this value in the next step.
      • API Endpoint - All IBM Blockchain Platform console API requests need be sent to this url. The curl examples in the right pane have the symbol {API-Endpoint}. Replace it (including the brackets) with the value of your API endpoint.
  • Access Token

    Authenticate your app or service by including your IBM Cloud (IAM) access token (also known as a bearer token) in API requests. To build this authorization header, you need an access token:

    1. To generate an access token, you must send the API key to an IAM exchange endpoint. The response will have an access/bearer token that is good for 1 hour. There is a curl example in the right pane -> and details below:

      • Method: POST
      • Endpoint: "https://iam.cloud.ibm.com/identity/token"
      • Data: "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={API_KEY}"
        • Replace {API_KEY} including the brackets with your key.

      Access tokens are valid for one hour, but you can regenerate them as needed. To maintain access to the service, refresh the access token regularly.

Build Header

Using the response of the access token api call you can now create the http Authorization header. This header authorizes all IBP console APIs (given the IAM API key has the necessary role). It should follow this format:

Authorization: Bearer {IAM-Token}
  • If you are using curl, the header can be set with this argument: -H "Authorization: Bearer {IAM-Token}"
  • Replace the value of {IAM-Token} (including the brackets) with your access_token field. However, note that the token generation response contains multiple fields. Use only the value of the access_token field.

API Key and API Endpoint.

The service credential looks similar to the following example, where the api_endpoint value is your API endpoint and the apikey value is your API key.

// example service credential:

{
  "api_endpoint": "https://d6457f496f3c496590ebfee3642adacc-optools.uss01.blockchain.cloud.ibm.com",

  "apikey": "--vs4eoUn7aBRRngGkgYKPqtP3h81ByLs7xHcqJ_aReu",

  "configtxlator": "https://d6457f496f3c496590ebfee3642adacc-configtxlator.uss01.blockchain.cloud.ibm.com",

  "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:staging:public:blockchain:us-south:a/9d46037caee397faa45c55e087d26baa:d6457f49-6f3c-4965-90eb-fee3642adacc::",

  "iam_apikey_name": "auto-generated-apikey-3ce5fc87-2845-4441-890f-e3517ced86a6",

  "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager",

  "iam_serviceid_crn": "crn:v1:staging:public:iam-identity::a/9d46037caee397faa45c55e087d26baa::serviceid:ServiceId-774190c5-9c37-4f68-8572-8d6e2aabbc7e"
}

Access Token

Open a terminal and call this IAM API to generate an access/bearer token. First, replace the {API_KEY} with the apikey value in your service credential.

curl -X POST "https://iam.cloud.ibm.com/identity/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={API_KEY}"

The response that is returned by this curl command contains multiple fields. Be sure to copy and use the value of the access_token field for the Bearer token authorization header.

// example response (values are abbreviated for brevity):
{
  "access_token": "eyJraWQiOiIyMDE5MDcyNCIsImFsZyI6IlJTMjU2In0.eyJpYW1faWQiTQzM...",

  "refresh_token": "OKCdugM9yM4QAuDqQBXC-FnkcqXGqbQPI5y3dWMDCNbUzXYIO-gwA0LzlFe...",

  "token_type": "Bearer",

  "expires_in": 3600,

  "expiration": 1577854800,

    "scope": "ibm openid"
}

Response Codes

The IBM Blockchain Platform APIs use standard HTTP response codes to indicate whether a method completed successfully. A 200-299 response code indicates a success. A 400-599 response code indicates a failure.

HTTP Error Code Description Recovery
2xx OK The request was successful. The response contains details.
4xx Invalid Request There is some issue with the request such as invalid permission, invalid input, or invalid route. Correct and try again.
5xx Internal Error The request could not be processed due to an internal issue or an issue with a dependency. Wait a few minutes and try again.

Rate Limits

All endpoints are protected by a rate limiter. If a client exceeds the limit, the server will not process the request and respond with a status code of 429. The client should back off and try the same request later.

Requests that do not alter state, such as one's with a GET method, have a default limit of 100 requests per min. Other APIs have a default limit of 25 requests per min.

  • The remaining requests a client can make (of the same type) before hitting the limit can be seen in the response header X-RateLimit-Remaining
  • When the limit is exceeded a UNIX timestamp (UTC) of when the client can retry is returned in the response header X-RateLimit-Reset
  • API rates are applied to individual clients

Examples

Curl

This page is broken up into three panes. The leftmost pane contains navigation. The middle pane has API documentation. The far right contains curl examples. A curl example appears to the right of each documented api. If you are unfamiliar with cURL, it is free software that allows you to send HTTP requests by using a command line interface. It is the quickest way to interact with the IBM Blockchain Platform APIs.

After curl is installed locally (it is often already installed by many operating systems), you can copy the example curl text and paste it into command line. Remember to replace the placeholders in the curl example with specific values for your service instance.

Most of the curl examples have dummy values. They need to be replaced to use the API. For example, the fields api_url, grpcwp_url, tls_cert, admins, root_certs & tls_root_certs in all curl examples are examples. They must be replaced with values for your components or identities.

In most cases the API will be rejected if the examples are left unchanged. This is especially true for certificate examples.

Postman

APIs are available to download a working Postman collection, which includes example API requests for all the APIs. If you are unfamiliar with Postman, it is free software that allows you to send and save HTTP requests by using a graphical user interface. It is easier to use than curl (less error prone).

See the Generate Postman collection APIs in the Download examples section to download a collection for your preferred auth. When Postman is installed, you can import this collection and then use Postman to interact with the APIs.

OpenAPI

There is an API to download the OpenAPI file (also known as the swagger file) that is used to build this page. If you are unfamiliar with OpenAPI, it is a file-based documentation standard that allows an application to document supported HTTP requests. Our version of the file documents the APIs offered by the IBM Blockchain Platform console. It is the same file that helped generate the API section below.

After you download the file, you can use it with various tools that support OpenAPI v3. For example, you can copy and paste the file into a swagger editor to browse the APIs we offer through an offline interface. See the Download OpenAPI file API in the Download examples section to get the swagger file.

Configuration override

You have the option of customizing a CA, peer, and ordering node configuration by using the configuration override field. Normally the components that are deployed by the IBM Blockchain console APIs are configured with default Fabric values that are provided by the fabric-ca-server-config.yaml, orderer.yaml, and core.yaml files. However, you can customize your component's settings by providing a configuration override in JSON to the APIs when you create a component. You can use the override to deploy a High Availability (HA) CA or deploy components that use a Hardware Security Module (HSM). For more information about the override, High Availability CAs, or HSMs, see Advanced deployment options.

You can find the configuration fields that are documented in the node configuration files:

Examples

Methods

Get component data

Get the IBP console's data on a component (peer, CA, orderer, or MSP). The component might be imported or created.

GET /ak/api/v2/components/{id}
Request

Path Parameters

  • The id of the component to retrieve. Use the Get all components API to determine the component id.

Query Parameters

  • Set to 'included' if the response should include Kubernetes deployment attributes such as 'resources', 'storage', 'zone', 'region', 'tls_cert', 'config_override', etc. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • Set to 'included' if the response should include parsed PEM data along with base 64 encoded PEM string. Parsed certificate data will include fields such as the serial number, issuer, expiration, subject, subject alt names, etc. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • Set to 'skip' if the response should skip local data and fetch live data wherever possible. Expect longer response times if the cache is skipped. Default responses will use the cache.

    Allowable values: [skip,use]

    Example: skip

  • Set to 'included' if the response should fetch CA attributes, inspect certificates, and append extra fields to CA and MSP component responses.

    • CA components will have fields appended/updated with data fetched from the /cainfo?ca=ca endpoint of a CA, such as: ca_name, root_cert, fabric_version, issuer_public_key and issued_known_msps. The field issued_known_msps indicates imported IBP MSPs that this CA has issued. Meaning the MSP's root cert contains a signature that is derived from this CA's root cert. Only imported MSPs are checked. Default responses will not include these fields.
    • MSP components will have the field issued_by_ca_id appended. This field indicates the id of an IBP console CA that issued this MSP. Meaning the MSP's root cert contains a signature that is derived from this CA's root cert. Only imported/created CAs are checked. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/components/{Component-ID}?cache=skip&deployment_attrs=included" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Contains the details of a component. Not all components have the same fields, see description of each field for details.

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Remove imported component

Remove a single component from the IBP console.

  • Using this api on an imported component removes it from the IBP console.
  • Using this api on a created component removes it from the IBP console but it will not delete the component from the Kubernetes cluster where it resides. Thus it orphans the Kubernetes deployment (if it still exists). Use the Delete component API to delete the Kubernetes deployment and the IBP console data at once.
DELETE /ak/api/v2/components/{id}
Request

Path Parameters

  • The id of the imported component to remove. Use the Get all components API to determine the component id.

  • curl -X DELETE "https://{API-Endpoint}/ak/api/v2/components/{Component-ID}" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Delete component

Removes a single component from the IBP console and it deletes the Kubernetes deployment.

  • Using this api on an imported component will error out since its Kubernetes deployment is unknown and cannot be removed. Use the Remove imported component API to remove imported components.
  • Using this api on a created component remove it from the IBP console and it will delete the component from the Kubernetes cluster where it resides. The Kubernetes delete must succeed before the component will be removed from the IBP console.
DELETE /ak/api/v2/kubernetes/components/{id}
Request

Path Parameters

  • The id of the component to delete. Use the Get all components API to determine the id of the component to be deleted.

  • curl -X DELETE "https://{API-Endpoint}/ak/api/v2/kubernetes/components/{Component-ID}" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Create a CA

Create a Hyperledger Fabric Certificate Authority (CA) in your Kubernetes cluster.

POST /ak/api/v2/kubernetes/components/fabric-ca
Request

Create a CA in your Kubernetes cluster.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-ca" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"display_name\": \"My CA\",
          \"config_override\":{
            \"ca\":{
              \"registry\":{
                \"maxenrollments\": -1,
                \"identities\": [{
                  \"name\": \"admin\",
                  \"pass\": \"password\",
                  \"type\": \"client\",
                  \"affiliation\": \"\",
                  \"attrs\":{
                          \"hf.Registrar.Roles\": \"*\",
                          \"hf.Registrar.DelegateRoles\": \"*\",
                          \"hf.Revoker\": true,
                          \"hf.IntermediateCA\": true,
                          \"hf.GenCRL\": true,
                          \"hf.Registrar.Attributes\": \"*\",
                          \"hf.AffiliationMgr\": true
                  }
                }]
              }
            }
          }
        }"
Response

Contains the details of a CA.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

Example responses

Import a CA

Import an existing Certificate Authority (CA) to your IBP console. It is recommended to only import components that were created by this or another IBP console.

POST /ak/api/v2/components/fabric-ca
Request

Import a CA.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/components/fabric-ca" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"name\": \"My Imported CA\",
          \"api_url\": \"https://n3a3ec3-myca.ibp.us-south.containers.appdomain.cloud:7054\",
          \"operations_url\": \"https://n3a3ec3-myca.ibp.us-south.containers.appdomain.cloud:9443\",
          \"ca_name\": \"ca\",
          \"tlsca_name\": \"tlsca\",
          \"tls_cert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\",
          \"location\": \"ibmcloud\"
        }"
Response

Contains the details of a CA.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

Example responses

Update a CA

Update Kubernetes deployment attributes of a Hyperledger Fabric Certificate Authority (CA) in your cluster.

PUT /ak/api/v2/kubernetes/components/fabric-ca/{id}
Request

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Update a CA in your Kubernetes cluster.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-ca/{Component-ID}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"resources\":{
            \"ca\":{
              \"requests\":{
                \"cpu\": \"200m\",
                \"memory\":\"256Mi\"
              }
            }
           }
        }"
Response

Contains the details of a CA.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Edit data about a CA

Modify local metadata fields of a Certificate Authority (CA). For example, the "display_name" field. This API will not change any Kubernetes deployment attributes for the CA.

PUT /ak/api/v2/components/fabric-ca/{id}
Request

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Edit local metadata about a CA. Send the fields that you want to edit in the body.

  • curl -X PUT "https://{API-Endpoint}/ak/api/v2/components/{Component-ID}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"display_name\": \"My Other CA\",
          \"tags\": [\"fabric-ca\", \"ibm_saas\", \"blue_team\", \"dev\"]
        }"
Response

Contains the details of a CA.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Create a peer

Create a Hyperledger Fabric peer in your Kubernetes cluster.

POST /ak/api/v2/kubernetes/components/fabric-peer
Request

Create a Hyperledger Fabric peer in your Kubernetes cluster.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-peer" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"display_name\": \"My Peer\",
          \"msp_id\": \"org2\",
          \"config\": {
            \"enrollment\": {
              \"component\": {
                \"cahost\": \"n3a3ec3-myca.ibp.us-south.containers.appdomain.cloud\",
                \"caport\": \"7054\",
                \"caname\": \"ca\",
                \"catls\": {
                  \"cacert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\"
                },
                \"enrollid\": \"admin\",
                \"enrollsecret\": \"password\",
                \"admincerts\": [
                  \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkFkbWluIGNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=\"
                ]
              },
              \"tls\": {
                \"cahost\": \"n3a3ec3-myca.ibp.us-south.containers.appdomain.cloud\",
                \"caport\": \"7054\",
                \"caname\": \"tlsca\",
                \"catls\": {
                  \"cacert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\"
                },
                \"enrollid\": \"admin\",
                \"enrollsecret\": \"password\",
                \"admincerts\": [
                  \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkFkbWluIGNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=\"
                ]
              }
            }
          },
          \"config_override\": {
            \"chaincode\": {
              \"startuptimeout\": \"480s\",
              \"executetimeout\": \"120s\"
            }
          }
        }"
Response

Contains the details of a peer.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

Example responses

Import a peer

Import an existing peer into your IBP console. It is recommended to only import components that were created by this or another IBP console.

POST /ak/api/v2/components/fabric-peer
Request

Import a peer.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/components/fabric-peer" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"display_name\": \"My Imported Peer\",
          \"location\": \"ibm cloud\",
          \"api_url\": \"grpcs://n3a3ec3-mypeer.ibp.us-south.containers.appdomain.cloud:7051\",
          \"msp_id\": \"PeerOrg1\",
          \"operations_url\": \"https://n3a3ec3-mypeer.ibp.us-south.containers.appdomain.cloud:9443\",
          \"grpcwp_url\": \"https://n3a3ec3-mypeer-proxy.ibp.us-south.containers.appdomain.cloud:8084\",
          \"tls_cert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\",
          \"tls_ca_root_cert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkRpZmZlcmVudCBkYXRhIGhlcmUgaWYgdGhpcyB3YXMgcmVhbAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==\"
        }"
Response

Contains the details of a peer.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

Example responses

Edit data about a peer

Modify local metadata fields of a peer. For example, the "display_name" field. This API will not change any Kubernetes deployment attributes for the peer.

PUT /ak/api/v2/components/fabric-peer/{id}
Request

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Edit a peer.

  • curl -X PUT "https://{API-Endpoint}/ak/api/v2/components/fabric-peer/{Component-ID}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"display_name\": \"My Other Peer\",
          \"msp_id\": \"peermsp\",
          \"tags\": [\"fabric-peer\", \"ibm_saas\", \"red_team\", \"prod\"]
        }"
Response

Contains the details of a peer.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Update a peer

Update Kubernetes deployment attributes of a Hyperledger Fabric Peer node.

PUT /ak/api/v2/kubernetes/components/fabric-peer/{id}
Request

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Update a peer in your Kubernetes cluster.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-peer/{Component-ID}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"resources\":{
            \"peer\":{
              \"requests\":{
                \"cpu\": \"400m\",
                \"memory\":\"800Mi\"
              }
            }
          }
        }"
Response

Contains the details of a peer.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Create an ordering service

Create a Hyperledger Ordering Service (OS) in your Kubernetes cluster. Currently, only raft ordering nodes are supported.

POST /ak/api/v2/kubernetes/components/fabric-orderer
Request

Create an ordering service in your Kubernetes cluster.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-orderer" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"orderer_type\": \"raft\",
          \"msp_id\": \"orderermsp\",
          \"config\": [<ConfigObject-Node-1>, <ConfigObject-Node-2>, <ConfigObject-Node-3>, <ConfigObject-Node-4>, <ConfigObject-Node-5>],
          \"cluster_name\": \"My three Node Raft\",
          \"display_name\": \"ordering service node\"
        }"
Response

Contains the details of an ordering node.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

Example responses

Import an ordering service

Import an existing Ordering Service (OS) to your IBP console. It is recommended to only import components that were created by this or another IBP console.

POST /ak/api/v2/components/fabric-orderer
Request

Import an ordering service.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/components/fabric-orderer" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
        \"display-name\": \"orderer node\",
        \"cluster_id\": \"abcde\",
        \"cluster_name\": \"My Raft OS\",
        \"grpcwp_url\": \"https://n3a3ec3-myorderer-proxy.ibp.us-south.containers.appdomain.cloud:443\",
        \"api_url\": \"grpcs://n3a3ec3-myorderer.ibp.us-south.containers.appdomain.cloud:7050\",
        \"operations_url\": \"https://n3a3ec3-myorderer.ibp.us-south.containers.appdomain.cloud:8443\",
        \"msp_id\": \"org1\",
        \"system_channel_id\": \"testchainid\",
        \"tls_cert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\",
        \"tls_ca_root_cert\": \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkRpZmZlcmVudCBkYXRhIGhlcmUgaWYgdGhpcyB3YXMgcmVhbAotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==\"
      }"
Response

Contains the details of an ordering node.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

Example responses

Edit data about an orderer

Modify local metadata fields of a single node in an Ordering Service (OS). For example, the "display_name" field. This API will not change any Kubernetes deployment attributes for the node.

PUT /ak/api/v2/components/fabric-orderer/{id}
Request

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Edit local metadata about an Orderer. Send the fields that you want to edit in the body.

  • curl -X PUT "https://{API-Endpoint}/ak/api/v2/components/fabric-orderer/{Component-ID}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"cluster_name\": \"My Other OS\",
          \"display_name\": \"ordering node\",
          \"msp_id\": \"orderermsp\"
        }"
Response

Contains the details of an ordering node.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Update an orderer node

Update Kubernetes deployment attributes of a Hyperledger Fabric Ordering node.

PUT /ak/api/v2/kubernetes/components/fabric-orderer/{id}
Request

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Update an orderer node in your Kubernetes cluster.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/fabric-orderer/{Component-ID}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"resources\":{
            \"orderer\":{
              \"requests\":{
                \"cpu\": \"500m\",
                \"memory\":\"1024Mi\"
              }
            }
          }
        }"
Response

Contains the details of an ordering node.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Submit config block to orderer

Send a config block (or genesis block) to a pre-created raft orderer node. Use this api to finish the raft-append flow and finalize a pre-created orderer. This is the final step to append a node to a raft cluster. The orderer will restart, load this block, and connect to the other orderers listed in said block.

The full flow to append a raft node:

  1. Pre-create the orderer with the Create an ordering service API (setting cluster_id is how you turn the normal create-orderer api into a pre-create-orderer api).
  2. Retrieve the pre-created node's tls cert with the Get component data API (set the deployment_attrs=included parameter).
  3. Get the latest config block for the system-channel by using the Fabric API (use a Fabric CLI or another Fabric tool).
  4. Edit the config block for the system-channel and add the pre-created orderer's tls cert and api url as a consenter.
  5. Create and marshal a Fabric ConfigUpdate proposal with configtxlator using the old and new block.
  6. Sign the ConfigUpdate proposal and create a ConfigSignature. Create a set of signatures that will satisfy the system channel's update policy.
  7. Build a SignedProposal out of the ConfigUpdate & ConfigSignature. Submit the SignedProposal to an existing ordering node (do not use the pre-created node).
  8. After the SignedProposal transaction is committed to a block, pull the latest config block (for the system-channel) from an existing ordering node (use a Fabric CLI or another Fabric tool).
  9. Submit the latest config block to your pre-created node with the 'Submit config block to orderer' API (which is this api!)
  10. Use the Edit data about an orderer API to change the pre-created node's field consenter_proposal_fin to true. This changes the status icon on the IBP console.
PUT /ak/api/v2/kubernetes/components/{id}/config
Request

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Send a config block.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/{Component-ID}/config" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"b64_block\":\"bWFzc2l2ZSBiaW5hcnkgb2YgYSBjb25maWcgYmxvY2sgd291bGQgYmUgaGVyZSBpZiB0aGlzIHdhcyByZWFs\"
        }"
Response

Contains the details of a component. Not all components have the same fields, see description of each field for details.

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Import an MSP

Create or import a Membership Service Provider (MSP) definition into your IBP console. This definition represents an organization that controls a peer or OS.

POST /ak/api/v2/components/msp
Request

Create or import an MSP.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/components/msp" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"msp_id\": \"org1\",
          \"display_name\": \"My First Org\",
          \"root_certs\": [\"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\"],
          \"admins\": [\"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkFkbWluIGNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=\"],
          \"tls_root_certs\": [
            \"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo\"
          ]
        }"
Response

Contains the details of an MSP (Membership Service Provider).

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

Example responses

Edit an MSP

Modify local metadata fields of a Membership Service Provider (MSP) definition. For example, the "display_name" property.

PUT /ak/api/v2/components/msp/{id}
Request

Path Parameters

  • The id of the component to modify. Use the Get all components API to determine the component id.

Edit an MSP.

  • curl -X PUT "https://{API-Endpoint}/ak/api/v2/components/{Component-ID}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"display_name\": \"My Other MSP\"
        }"
Response

Contains the details of an MSP (Membership Service Provider).

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Get MSP's public certificates

External IBP consoles can use this API to get the public certificate for your given MSP id.

GET /ak/api/v2/components/msps/{msp_id}
Request

Path Parameters

  • The msp_id to fetch

Query Parameters

  • Set to 'skip' if the response should skip local data and fetch live data wherever possible. Expect longer response times if the cache is skipped. Default responses will use the cache.

    Allowable values: [skip,use]

    Example: skip

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/components/msps/{Component-ID}" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Edit admin certs on a component

This api will append or remove admin certs to the components' file system. Certificates will be parsed. If invalid they will be skipped. Duplicate certificates will also be skipped.

PUT /ak/api/v2/kubernetes/components/{id}/certs
Request

Path Parameters

  • The id of the component to edit. Use the Get all components API to determine the id of the component.

Import an MSP.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/kubernetes/components/{Component-ID}/certs" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"append_admin_certs\": [\"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCkNlcnQgZGF0YSB3b3VsZCBiZSBoZXJlIGlmIHRoaXMgd2FzIHJlYWwKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=\"],
          \"remove_admin_certs\": []
        }"
Response

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Get all components

Get the IBP console's data on all components (peers, CAs, orderers, and MSPs). The component might be imported or created.

GET /ak/api/v2/components
Request

Query Parameters

  • Set to 'included' if the response should include Kubernetes deployment attributes such as 'resources', 'storage', 'zone', 'region', 'tls_cert', 'config_override', etc. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • Set to 'included' if the response should include parsed PEM data along with base 64 encoded PEM string. Parsed certificate data will include fields such as the serial number, issuer, expiration, subject, subject alt names, etc. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • Set to 'skip' if the response should skip local data and fetch live data wherever possible. Expect longer response times if the cache is skipped. Default responses will use the cache.

    Allowable values: [skip,use]

    Example: skip

  • Set to 'included' if the response should fetch CA attributes, inspect certificates, and append extra fields to CA and MSP component responses.

    • CA components will have fields appended/updated with data fetched from the /cainfo?ca=ca endpoint of a CA, such as: ca_name, root_cert, fabric_version, issuer_public_key and issued_known_msps. The field issued_known_msps indicates imported IBP MSPs that this CA has issued. Meaning the MSP's root cert contains a signature that is derived from this CA's root cert. Only imported MSPs are checked. Default responses will not include these fields.
    • MSP components will have the field issued_by_ca_id appended. This field indicates the id of an IBP console CA that issued this MSP. Meaning the MSP's root cert contains a signature that is derived from this CA's root cert. Only imported/created CAs are checked. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/components" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Contains the details of multiple components the UI has onboarded.

Status Code

  • Successful response.

  • No components.

  • Unauthorized response.

  • Forbidden response.

Example responses

Get components of a type

Get the IBP console's data on components that are a specific type. The component might be imported or created.

GET /ak/api/v2/components/types/{component-type}
Request

Path Parameters

  • The type to filter components on.

    Allowable values: [fabric-peer,fabric-orderer,fabric-ca,msp]

Query Parameters

  • Set to 'included' if the response should include Kubernetes deployment attributes such as 'resources', 'storage', 'zone', 'region', 'tls_cert', 'config_override', etc. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • Set to 'included' if the response should include parsed PEM data along with base 64 encoded PEM string. Parsed certificate data will include fields such as the serial number, issuer, expiration, subject, subject alt names, etc. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • Set to 'skip' if the response should skip local data and fetch live data wherever possible. Expect longer response times if the cache is skipped. Default responses will use the cache.

    Allowable values: [skip,use]

    Example: skip

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/components/types/{Component-Type}" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Contains the details of multiple components the UI has onboarded.

Status Code

  • Successful response.

  • No components.

  • Unauthorized response.

  • Forbidden response.

Example responses

Get components with tag

Get the IBP console's data on components that have a specific tag. The component might be imported or created. Tags are not case-sensitive.

GET /ak/api/v2/components/tags/{tag}
Request

Path Parameters

  • The tag to filter components on. Not case-sensitive.

Query Parameters

  • Set to 'included' if the response should include Kubernetes deployment attributes such as 'resources', 'storage', 'zone', 'region', 'tls_cert', 'config_override', etc. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • Set to 'included' if the response should include parsed PEM data along with base 64 encoded PEM string. Parsed certificate data will include fields such as the serial number, issuer, expiration, subject, subject alt names, etc. Default responses will not include these fields.

    Allowable values: [included,omitted]

    Example: included

  • Set to 'skip' if the response should skip local data and fetch live data wherever possible. Expect longer response times if the cache is skipped. Default responses will use the cache.

    Allowable values: [skip,use]

    Example: skip

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/components/tags/fabric-peer" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Contains the details of multiple components the UI has onboarded.

Status Code

  • Successful response.

  • No components.

  • Unauthorized response.

  • Forbidden response.

Example responses

Remove components with tag

Removes components with the matching tag from the IBP console. Tags are not case-sensitive.

  • Using this api on an imported component removes it from the IBP console.
  • Using this api on a created component removes it from the IBP console but it will not delete the component from the Kubernetes cluster where it resides. Thus it orphans the Kubernetes deployment (if it still exists). See the Delete components with tag API to delete the Kubernetes deployment.
DELETE /ak/api/v2/components/tags/{tag}
Request

Path Parameters

  • The tag to filter components on. Not case-sensitive.

  • curl -X DELETE "https://{API-Endpoint}/ak/api/v2/components/{Tag}" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Delete components with tag

Removes components with the matching tag from the IBP console and it deletes the Kubernetes deployment. Tags are not case-sensitive.

  • Using this api on an imported component will error out since its Kubernetes deployment is unknown and cannot be removed. Use the Remove components with tag API to remove imported components with a tag.
  • Using this api on a created component removes it from the IBP console but it will not delete the component from the Kubernetes cluster where it resides. Thus it orphans the Kubernetes deployment (if it still exists).
DELETE /ak/api/v2/kubernetes/components/tags/{tag}
Request

Path Parameters

  • The tag to filter components on. Not case-sensitive.

  • curl -X DELETE "https://{API-Endpoint}/ak/api/v2/kubernetes/components/tags/{Tag}" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Delete all components

Removes all components from the IBP console and their Kubernetes deployments (if applicable).

DELETE /ak/api/v2/kubernetes/components/purge
Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X DELETE "https://{API-Endpoint}/ak/api/v2/kubernetes/components/purge" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Get public IBP console settings

Retrieve all public (non-sensitive) settings for the IBP console. Use this API for debugging purposes. It shows what behavior to expect and confirms whether the desired settings are active.

GET /ak/api/v2/settings
Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/settings" \
    -H "Content-Type: application/json"
Response

Contains the details of all public settings for the UI

Status Code

  • Successful response.

No Sample Response

This method does not specify any sample responses.

Get IBP console health stats

See statistics of the IBP console process such as memory usage, CPU usage, up time, cache, and operating system stats.

GET /ak/api/v2/health
Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/health" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Contains various health statistics like up time and cache sizes.

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Get all notifications

Retrieve all notifications. This API supports pagination through the query parameters. Notifications are generated from actions such as creating a component, deleting a component, server restart, and so on.

GET /ak/api/v2/notifications
Request

Query Parameters

  • The number of notifications to return. The default value is 100.

    Constraints: 1 ≤ value ≤ 1024

  • skip is used to paginate through a long list of sorted entries. For example, if there are 100 notifications, you can issue the API with limit=10 and skip=0 to get the first 1-10. To get the next 10, you can set limit=10 and skip=10 so that the values of entries 11-20 are returned.

    Constraints: 1 ≤ value ≤ 1024

  • Filter response to only contain notifications for a particular component id. The default response will include all notifications.

    Example: MyPeer

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/notifications?limit=20&skip=0" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

  • Not found.

Example responses

Get signature collection txs

Get all signature collection transactions. These transactions involve creating or editing Fabric channels. The only transactions that are listed are ones that involved this IBP console. Channels that are edited or created outside of the IBP console are not discoverable.

GET /ak/api/v2/signature_collections
Request

Query Parameters

  • Set to 'omitted' if the responses should be kept short and include only a summary of the transaction. The default response will include the long details.

    Allowable values: [included,omitted]

    Example: included

  • Filter response to only contain transactions of certain orderer hostnames. Include the hostname and port of one or more orderers. The default response will not filter out transactions. The query parameter should resemble an array of strings.

    Example: ["my-orderer.ibp.us-south.containers.appdomain.cloud:3010"]

  • Set to 'channels' if an alternative response format should be used where transactions are bucketed by channel names (A 210 status code and response will be sent). The default response will not group transactions.

    Allowable values: [channels,none]

    Example: included

  • Set to 'skip' if the response should skip local data and fetch live data wherever possible. Expect longer response times if the cache is skipped. Default responses will use the cache.

    Allowable values: [skip,use]

    Example: skip

  • Filter response to only contain transactions in a desired status state. The default response will not filter out transactions.

    Allowable values: [all,closed,open]

    Example: all

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/signature_collections?cache=skip&full_details=omitted" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Status Code

  • Successful response.

  • Successful alternative response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Archive notifications

Archive 1 or more notifications. Archived notifications will no longer appear in the default Get all notifications API.

POST /ak/api/v2/notifications/bulk
Request

Archive notifications

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/notifications/bulk" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"notification_ids\": [
              \"edf0c5e0b76d49ccadb8eee3eec88a48\",
              \"c9d00ebf849051e4f102008dc0be2488\",
              \"d7d831ddcd8d8c5bf87f4d972f675096\"
          ]
        }"
Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Restart the IBP console

Restart IBP console processes. This causes a small outage (10 - 30 seconds) which is possibly disruptive to active user sessions.

POST /ak/api/v2/restart
Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X POST "https://{API-Endpoint}/ak/api/v2/restart" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Describes the outcome of the api.

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Change logging settings

Change your IBP console's file logging settings. Settings that are omitted from the request body will remain as is.

PUT /ak/api/v2/logs/file_settings
Request

Include only the settings that you want to change, and the other settings will remain as is.

  • curl -X PUT "https://{API-Endpoint}/ak/api/v2/logs/file_settings" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}" \
    -d "{
          \"client\": {
            \"enabled\": true,
            \"level\": \"debug\",
            \"unique_name\": false
          },
          \"server\": {
            \"enabled\": true,
            \"level\": \"info\",
            \"unique_name\": false
          }
        }"
Response

The logging settings for the client and server.

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

Example responses

Delete all IBP console sessions

Delete all client sessions in IBP console. Use this API to clear any active logins and force everyone to log in again. This API is useful for debugging purposes and when changing roles of a user. It forces any role changes to take effect immediately. Otherwise, permission or role changes will take effect during the user's next login or session expiration.

DELETE /ak/api/v2/sessions
Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X DELETE "https://{API-Endpoint}/ak/api/v2/sessions" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer {IAM-Token}"
Response

Describes the outcome of the api.

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Delete all notifications

Delete all notifications. This API is intended for administration.

DELETE /ak/api/v2/notifications/purge
Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X DELETE "https://{API-Endpoint}/ak/api/v2/notifications/purge" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Clear IBP console caches

Clear out in-memory caches in the IBP console processes. No effect on caches that are currently disabled.

DELETE /ak/api/v2/cache
Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X DELETE "https://{API-Endpoint}/ak/api/v2/cache" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Generate Postman collection

Generate and download a Postman API Collection. The JSON contains all the APIs available in the IBP console. It can be imported to the Postman desktop application. The examples in the collection will be pre-populated with authorization credentials. The authorization credentials to use must be provided to this API. See the query parameters for available options.

Choose an auth strategy that matches your environment & concerns:

  • IAM Bearer Auth - [Available on IBM Cloud] - This is the recommended auth strategy. The same bearer token used to authenticate this request will be copied into the Postman collection examples. Since the bearer token expires the auth embedded in the collection will also expire. At that point the collection might be deleted & regenerated, or manually edited to refresh the authorization header values. To use this strategy set auth_type to bearer.
  • IAM Api Key Auth - [Available on IBM Cloud] - The IAM api key will be copied into the Postman collection examples. This means the auth embedded in the collection will never expire. To use this strategy set auth_type to api_key.
  • Basic Auth - [Available on OpenShift & IBM Cloud Private] - A basic auth username and password will be copied into the Postman collection examples. This is not available for an IBP SaaS instance on IBM Cloud. To use this strategy set auth_type to basic.
GET /ak/api/v2/postman
Request

Query Parameters

    • bearer - IAM Bearer Auth - [Available on IBM Cloud] - The same bearer token used to authenticate this request will be copied into the Postman collection examples. The query parameter token must also be set with your IAM bearer/access token value.
    • api_key - IAM Api Key Auth - [Available on IBM Cloud] - The IAM api key will be copied into the Postman collection examples. The query parameter api_key must also be set with your IAM API Key value.
    • basic - Basic Auth - [Available on OpenShift & IBM Cloud Private] - A basic auth username and password will be copied into the Postman collection examples. The query parameters username & password must also be set with your IBP api key credentials. The IBP api key is the username and the api secret is the password.

    Allowable values: [bearer,api_key,basic]

    Example: included

  • The IAM access/bearer token to use for auth in the collection.

  • The IAM api key to use for auth in the collection.

  • The basic auth username to use for auth in the collection.

    Example: admin

  • The basic auth password to use for auth in the collection.

    Example: password

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/postman?auth_type=bearer&token={IAM-Token}" \
    -H "Authorization: Bearer {IAM-Token}"
Response

Postman v2.1 collection file (JSON). Postman's JSON structure is not documented here for brevity. Save JSON as a file and import the file into your Postman desktop application.

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

Download OpenAPI file

Download the OpenAPI specification file (aka swagger file) for the IBP console. This is the same file that was used to generate the APIs on this page. The file documents APIs offered by IBP console.

GET /ak/api/v2/openapi
Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X GET "https://{API-Endpoint}/ak/api/v2/openapi" \
    -H "Authorization: Bearer {IAM-Token}"
Response

OpenAPI v3.0.0 file (yaml). OpenAPI/Swagger JSON structure is not documented here for brevity. Save JSON as a file and import into OpenAPI tools.

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

(Software) - Create an IBP api key

(IBP Software only) - Create an IBP api key. This key can be used to authenticate and call other APIs. Only users or api keys with a manager role can call this api. The api_secret in the response must be saved by the user. It is unrecoverable. API keys do not expire but can be deleted.

POST /ak/api/v2/permissions/keys
Request

Pass the desired roles for the new api key. Valid roles - "reader", "writer", "manager".

Response

Status Code

  • Successful response.

  • Bad request.

  • Unauthorized response.

  • Forbidden response.

Example responses

(Software) - List IBP api keys

(IBP Software only) - List all IBP api keys and their descriptions. The api secrets will not be in the response.

GET /ak/api/v2/permissions/keys
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

(Software) - Delete an api key

(IBP Software only) - Delete a single IBP api key. The key becomes unusable immediately.

DELETE /ak/api/v2/permissions/keys/{key_id}
Request

Path Parameters

  • The api_key to delete.

Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

(Software) - Add users

(IBP Software only) - Add new users to the IBP console. Users can log in and perform operations IBP console operations. Only users or api keys with a manager role can call this api.

POST /ak/api/v2/permissions/users
Request

Pass the desired roles for the usernames. Valid roles - "reader", "writer", "manager".

Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

(Software) - Delete users

(IBP Software only) - Delete existing users by uuid. Only users or api keys with a manager role can call this api. Note that uuids are expected, not usernames.

DELETE /ak/api/v2/permissions/users
Request

Query Parameters

  • Pass the desired uuids to delete. The query parameter should resemble an array of strings.

    Example: ["b26e67a3-8f4c-40e4-b5e2-6303ad2979fc"]

Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

(Software) - Edit users

(IBP Software only) - Edit existing users by uuid. Only users or api keys with a manager role can call this api. Note that uuids are expected, not usernames.

PUT /ak/api/v2/permissions/users
Request

Pass the desired roles for the usernames. Valid roles - "reader", "writer", "manager".

Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

(Software) - List users

(IBP Software only) - List users of the IBP console. Includes the user's roles and the timestamp of when it was added.

GET /ak/api/v2/permissions/users
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses

(Software) - Reset users' passwords

(IBP Software only) - Reset multiple user passwords to the default password. The default password was chosen when IBP console was initially set up. Only users or api keys with a manager role can call this api.

PUT /ak/api/v2/permissions/users/password/reset
Request

Pass an array of uuids to reset.

Response

Status Code

  • Successful response.

  • Unauthorized response.

  • Forbidden response.

Example responses