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.

IBM Blockchain Platform exposes several RESTful APIs, so that you can create and manage your network components. These APIs are compatible only with the IBM Blockchain Platform v0.1.77 or higher. To check your version, browse to https://[your_console_url]/version.txt, where [your_console_url] is the URL of your IBM Blockchain Platform console. For more information about the IBM Blockchain Platform, see Getting started with IBM Blockchain Platform on IBM Cloud or if you are using the APIs with IBM Cloud Private, see Getting started with IBM Blockchain Platform for Multicloud.

These APIs are for provisioning the infrastructure only. You must still use the Fabric CA client APIs to register and enroll users. Also, you can use the Fabric Node SDK or peer CLI commands to install and instantiate smart contracts.

Authentication (IBM Cloud only)

To authenticate, you need to gather the following information. If you intend to use the APIs with IBM Cloud Private, refer to these instructions for authentication.

  • API key and API endpoint
    The API key is a string that you can use to authenticate your access to your IBM Blockchain Platform service instance. The API endpoint is a url, that allows you to access your service instance through the APIs.

    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, for example, Manager.
      2. Select a role, which can be Manager, Writer, and Reader. For more information about each role, see the table in Add and remove users from the console.
      3. Click the Add button.
    4. After the new credential is created, click View credentials under the ACTIONS header of this credential. The api_endpoint value is your API endpoint and the apikey value is your API key.
  • IAM access token
    To use the IBM Blockchain Platform APIs, authenticate your app or service by including your IBM Cloud Identity and Access Management (IAM) access token in API requests.

    Access tokens are valid for one hour, but you can regenerate them as needed. To maintain access to the service, refresh the access token for your API key on a regular basis by calling the Cloud Identity and Access Management API.

You can use the Try it out tab on top of the right column to test the APIs. For each API, you need to specify your API endpoint and pass in the Bearer access token in the Authorization field in the format of Bearer <access_token>. For example:

Bearer eyJraWQiOiIyMDE4MDcwMSIsImFsZyI6IlJTMjU2In0.eyJpYW1faWQiOiJpYW0tU2VydmljZUlkLTJkNTFkNTZiLTc3MzMtNDJhYS1hOTdkLTQzMjk

Enter any parameter values that you need to specify, and then click the Try it out button. You must be logged in to IBM Cloud in order to use the Try it out function. You can select any service instance from the drop-down list. All API requests are sent to the network specified in the API endpoint. The Try it out button cannot be used with IBM Blockchain Platform for IBM Cloud Private.

Create a new service credential for your service instance and click View credentials under the ACTIONS header of the credential to see the results. 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.

{
  "api_endpoint": "https://d6457f496f3c496590ebfee3642adacc-optools.so01.blockchain.test.cloud.ibm.com",
  "apikey": "--vs4eoUn7aBRRngGkgYKPqtP3h81ByLs7xHcqJ_aReu",
  "configtxlator": "https://d6457f496f3c496590ebfee3642adacc-configtxlator.so01.blockchain.test.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"
}

Call the IAM API to retrieve your access token, which is the access_token value in the response.

curl -X POST \
   https://iam.cloud.ibm.com/identity/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"

Replace <API_KEY> with the apikey value in your service credential. Important: The response that is returned by this curl command contains your token, the access_token, followed by a refresh_token. Be sure to only copy and use the value of the access_token for the Bearer parameter in the APIs.

Error handling

The IBM Blockchain Platform APIs use standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 401 type response indicates a failure on authentication, and a 500 type response indicates an internal system error.

HTTP Error Code Description Recovery
200 Success The request was successful.
401 Unauthorized You are not authorized to make this request.
500 Internal Server Error IBM Blockchain Platform is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Pagination

Some API requests might return a large number of results. By specifying the limit and offset parameters at query time, you can retrieve a subset of your keys, starting with the offset value that you specify.

Methods

Get all components

Get all components from the console database. The components include peers, CAs, orderers, MSPs, and so on.

GET /ak/api/v1/components
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Response

Status Code

  • Successful and returns an array of all components.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Create a CA

Create a CA in your Kubernetes cluster.

POST /ak/api/v1/kubernetes/components/ca
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Create a CA in your Kubernetes cluster.

Response

Details for your component are returned

Status Code

  • Successful and the CA is created in your Kubernetes cluster.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Import a CA

Import an existing CA to your console. You can only use this API to import IBM Blockchain components created by using these APIs or another IBM Blockchain Platform console.

POST /ak/api/v1/components/ca
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Import a CA.

Response

Details for your Fabric component are returned

Status Code

  • Successful and the CA is imported.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Edit a CA

Modify one or more properties in a CA. For example, the "display_name" property.

PUT /ak/api/v1/components/ca/{id}
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Path Parameters

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

Edit a CA.

Response

Details for your Fabric component are returned

Status Code

  • Successful and CA properties are updated.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Create an ordering service

Create a Raft ordering service in your Kubernetes cluster.

POST /ak/api/v1/kubernetes/components/orderer
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Create an ordering service in your Kubernetes cluster.

Response

Details for your component are returned

Status Code

  • Successful and the orderer is created in your Kubernetes cluster.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Import an ordering service

Import an existing orderer to your console. You can only use this API to import IBM Blockchain components created by using these APIs or another IBM Blockchain Platform console.

POST /ak/api/v1/components/orderer
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Import an ordering service.

Response

Details for your Fabric component are returned

Status Code

  • Successful and the orderer is imported.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Edit an ordering service

Modify one or more properties in an orderer. For example, the "display_name" property.

PUT /ak/api/v1/components/orderer/{id}
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Path Parameters

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

Edit an ordering service.

Response

Details for your Fabric component are returned

Status Code

  • Successful and the orderer properties are updated.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Create a peer

Create a peer in your Kubernetes cluster.

POST /ak/api/v1/kubernetes/components/peer
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Create a peer in your Kubernetes cluster.

Response

Details for your component are returned

Status Code

  • Successful and the peer is created in your Kubernetes cluster.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Import a peer

Import an existing peer into your console. You can only use this API to import IBM Blockchain components created by using these APIs or another IBM Blockchain Platform console.

POST /ak/api/v1/components/peer
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Import a peer.

Response

Details for your Fabric component are returned

Status Code

  • Successful and the peer is imported.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Edit a peer

Modify one or more properties in a peer. For example, the "display_name" property.

PUT /ak/api/v1/components/peer/{id}
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Path Parameters

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

Edit a peer.

Response

Details for your Fabric component are returned

Status Code

  • Successful and the peer properties are updated.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Import a Membership Service Provide (MSP)

Import an MSP definition into your console. You can use this definition to represent the peer or orderer organization.

POST /ak/api/v1/components/msp
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Import an MSP.

Response

Details for your component are returned

Status Code

  • Successful and the new MSP is imported.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Edit an MSP

Modify one or more properties in an MSP definition. For example, the "fabric_node_ous" property.

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

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Path Parameters

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

Edit an MSP.

Response

Details for your Fabric component are returned

Status Code

  • Successful and the MSP properties are updated.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Get a local MSP's certificate

External party's IBM Blockchain Platform consoles can use this API to get the public certificate for a given MSP id.

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

Custom Headers

  • No authorization required, this is publicly available.

Path Parameters

  • The msp_id to fetch

Response

Status Code

  • Successful and the local msp's certificate is returned.

No Sample Response

This method does not specify any sample responses.

Get a component

Get the parameters for a single component by specifying its id.

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

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Path Parameters

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

Response

Status Code

  • Successful and returns an object of the component.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Remove an imported component

Remove a single component that was imported to the console. Note this action does not delete the component from the Kubernetes cluster where it resides. It simply removes it from the IBM Blockchain Platform console.

DELETE /ak/api/v1/components/{id}
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Path Parameters

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

Response

Status Code

  • Successful and the component is deleted.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Delete a component

Delete a single component from your IBM Blockchain Platform console and from your Kubernetes cluster. A component can be a peer, CA, or orderer.

DELETE /ak/api/v1/kubernetes/components/{id}
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

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.

Response

Status Code

  • Successful and the component is deleted from your Kubernetes cluster.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Delete all components

Delete all components in your Kubernetes cluster. The components include Fabric peers, CAs, and orderers.

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

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Response

Status Code

  • Successful and all componentes are deleted from your Kubernetes cluster.

  • Unauthorized

No Sample Response

This method does not specify any sample responses.

Change logging settings

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

PUT /ak/api/v1/logs/file_settings
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

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

Response

The (new) settings are returned.

Status Code

  • Successful and the updated settings are returned.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Get notifications

Retrieve all notifications. Use this API to paginate through notifications. Possible notifications include actions such as creating a component, deleting a component, server restart, and so on.

GET /ak/api/v1/notifications
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Query Parameters

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

  • 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.

Response

Status Code

  • Successful and all notifications are returned.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Delete all notifications

Delete all notifications. This API is intended for debugging and administration.

DELETE /ak/api/v1/notifications/purge
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Response

Status Code

  • Successful and all notifications are deleted.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Get settings for the IBM Blockchain Platform console

Retrieve all non-sensitive settings for IBM Blockchain Platform console. Use this API for debugging purposes and to view the current settings. This API informs you of what behavior to expect and confirms whether the desired settings are active.

GET /ak/api/v1/settings
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Response

Status Code

  • Successful and the IBM Blockchain Platform console settings are returned.

No Sample Response

This method does not specify any sample responses.

Restart IBM Blockchain Platform console

Restart the IBM Blockchain Platform console process.

POST /ak/api/v1/restart
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Response

Status Code

  • Successful and IBM Blockchain Platform console is restarted.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Delete all IBM Blockchain Platform console sessions

Delete all client sessions in IBM Blockchain Platform console. Use this API to delete all client sessions in order to clear any active logins and force everyone to login again. This API is useful for debugging purposes and when you change roles of a user and want those 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/v1/sessions
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Response

Status Code

  • Successful and all sessions are deleted.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.

Get IBM Blockchain Platform console health stats

See memory and CPU usage for the console process and other OS stats.

GET /ak/api/v1/health
Request

Custom Headers

  • The IAM access token.

    Example: Bearer <token>

Response

Status Code

  • Successful and health statistics are returned.

  • Unauthorized.

No Sample Response

This method does not specify any sample responses.