solution-manager-api.md

copyright	lastupdated
years 2018	2018-04-27

{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:codeblock: .codeblock} {:pre: .pre}

Blockchain Solution Manager API

The Blockchain Solution Manager API enables authenticated, authorized users (humans, systems and applications) to manage blockchain networks, solutions, organizations, roles and users. All tasks are done by making a Blockchain Solution Manager API (Swagger) {:new_window} call.

Descriptions of the Blockchain Solution Manager API endpoints are provided below. To manually call an endopoint, use the Swagger interface {:new_window}.

Attention: The defined roles that are authorized to call each endpoint are also listed in Blockchain Solution Manager API ACLs.

Swagger API interface

In the Blockchain Solution Manager API {:new_window}, click any endpoint to view the description, parameters and responses. Click Try it out! to enter test values, and click Execute to view the test responses (Figure 1.):

Figure 1. Blockchain Solution Manager API

Authorization

To get authorized (OAuth 2.0) to call Blockchain Solution Manager API endpoints, click the green Authorize lock icon in the upper right of the Blockchain Solution Manager API (Swagger) {:new_window}. Enter your Onboarding Token (Bearer); authorization to call specific endpoints will be granted based on your assigned roles. An XUserToken is also required only when calling the Blockchain /v1/networks/certificates/enrollment_certificates endpoint. Click Authorize to submit your token.

API endpoints

The following API endpoints are available for managing your blockchain networks, solutions, organizations, roles and users, at Blockchain Solution Manager API {:new_window}.

Note: All Models are documented in the Blockchain Solution Manager API {:new_window}.

Admin

GET /v1/administrators

Retrieves the registered Network Administrators for an instance of Blockchain Solution Manager. The caller must be a Network Administrator.

POST /v1/administrators

Adds (registers) Network Administrators to an instance of IBM Blockchain Solution Manager. The caller must be a Network Administrator.

DELETE /v1/administrators

Deletes Network Administrators from an instance of IBM Blockchain Solution Manager. The caller must be a Network Administrator.

PUT /v1/idp

Stores or updates an identity provider configuration for the network. An identity provider configuration is defined according to the relying party configuration, or dynamic profiles of the OpenID Connect protocol. The caller must be a Network Administrator.

GET /v1/idp

Retrieves the identity provider configurations for the network. The caller must be a Network Administrator.

GET /v1/idp/{name}

Retrieves the specified identity provider configuration file {name}. The caller must be a Network Administrator.

DELETE /v1/idp/{name}

Deletes the specified identity provider configuration file {name}. The caller must be a Network Administrator.

Blockchain

PUT /v1/networks

Adds a member organization to the blockchain network, based on the specified network connection profile (service credential JSON from an IBM Blockchain account). The member, channels, and nodes (peers) specified in the Blockchain Network Connection Profile are created. The caller must be a Network Administrator or Service Broker.

GET /v1/networks/{networkID}

Retrieves the Blockchain Network Configuration Profiles (blockchain networks). The caller must be a Network Administrator.

GET /v1/networks/certificates/admin_public_certificates

Retrieves the **Chaincode Administrator Certificate** for the network. The caller must be a Network Administrator or Solution Administrator.
**Parameters**:
*networkId* - Blockchain Network ID (The *x-networkId* values in your IBM Blockchain Platform connection profile)"
*memberId* - MSP ID of the member organization.

GET /v1/networks/certificates/enrollment_certificates

Retrieves the network **Enrollment Certificate** for the specified user. The caller must be a Solution Administrator.
**Parameters**:
*roleId* - Unique identifier (UUID) of the **Role**. This parameter **is required if** the attribution to transaction of the organization is based on roles for the user's organization.
*oid* - Required. Organization ID for the user.
*sid* - Required. Solution ID for the user.
*uid* - Required. Unique identifier (UUID) for the user.

GET /v1/networks/credentials/channels

Retrieves the connection profile for the specified channel.
**Parameters:**
*channelId* - Required. The ID of the channel.
*networkId* - Required. The ID of the network./dd>

Solution

PUT /v1/solutions

Creates or updates an instance of an IBM Blockchain Solution. The caller must be a Network Administrator. To specify accounts (users), the networkId and memberId must have already been registered by a call to the **/v1/networks/{network_id}** endpoint. **If no accounts (users) are specified**, this API creates the network.
**Parameters**:
*solutionId* - Required if a solution is being updated. ID of the Solution to be updated.
*onboardingdata* - A JSON object specifying the solution parameters to create or update.

GET /v1/solutions

If a *solutionId* is **not** specified, retrieves the solution IDs. If a solutionId is specified, exports the solution. The authenticated user must be a Network Administrator.
**Parameters**:
*solutionId* - Required to export a solution. ID of a solution to be exported.

Organizations

PUT /v1/organizations

Creates or updates a member organization. The caller must be a Network Administrator or Solution Administrator.
**Parameters**:
*organization* - The name of the organization to create.
*solutionId* - UUID of a solution associated with the organization.

GET /v1/organizations/{organizationId}

Retrieves organization information. The caller must be a Network Administrator, Solution Administrator or Organization Administrator.
Parameters:
*solutionId* - UUID of a solution associated with the organization.
*organizationId* - Required. UUID of the organization.

GET /v1/organizations/{organizationId}/administrators

Retrieves the administrators for the organization. The caller must be a Network Administrator, Solution Administrator or Organization Administrator.
**Parameters**:
*solutionId* - UUID of a solution associated with the organization.
*organizationId* - Required. UUID of the organization.

POST /v1/organizations/{organizationId}/administrators

Adds one or more administrators to an organization. The caller must be a Network Administrator, Solution Administrator or Organization Administrator.
Parameters:
*solutionId* - UUID of a solution associated with the organization.
*organizationId* - Required. UUID of the organization.
*administrators* - Required. Administrator accounts (email addresses) to add.

DELETE /v1/organizations/{organizationId}/administrators

Deletes administrators from the organization. The caller must be a Network Administrator, Solution Administrator or Organization Administrator.
**Parameters:**
*solutionId* - UUID of a solution associated with the organization.
*organizationId* - Required. UUID of the organization.
*administrators* - Administrator accounts to delete.

Roles

PUT /v1/roles

Creates or replaces the defined roles for the solution. The caller must be a Network Administrator or Solution Administrator.
**Parameters**:
*solutionId* - UUID of the solution. If not specified, roles are added to the default *solutionId*.
*roles* - Required. A list (array) of role definitions.

GET /v1/roles

Retrieves the defined roles for the solution. A Network Administrator can retrieve the roles for any solution. Any user can retrieve the roles for their solution.
**Parameters**:
*solutionId* - UUID of the solution. If not specified, roles are retrieved from the default *solutionId*.

PUT /v1/roles/{roleId}

Creates or replaces a defined role for the solution. The caller must be a Network Administrator or Solution Administrator.
**Parameters**:
*solutionId* - UUID of the solution. If not specified, the role is added to the default *solutionId*.
**roleId* - Required. The role object (name) to create.

DELETE /v1/roles/{roleId}

Deletes a defined role from the solution. The caller must be a Network Administrator or Solution Administrator.
**Parameters**:
*solutionId* - UUID of the solution. If not specified, the role is deleted from the default *solutionId*.
*roleId* - Required. The UUID of the role to delete.

GET /v1/roles/{roleId}

Retrieves the defined roles for the specified Role ID. A Network Administrator can retrieve the role ID information for any solution. Any user can retrieve role ID information for their solution.
**Parameters**:
*solutionId* - UUID of the solution. If not specified, the role is retrieved from the default *solutionId*.
*roleId* - Required. UUID of the role to retrieve.

Organization Types

PUT /v1/organization_types

Creates or replaces organization types for the solution. The caller must be a Network Administrator or Solution Administrator.
**Parameters**:
*solutionId* - UUID of the solution. If not specified, the organization types are retrieved from the default *solutionId*.
*orgtypes* - Required. A list (array) of organization types.

GET /v1/organization_types

Retrieves the defined organization types for the solution. The caller must be an authenticated Network Administrator.
**Parameters**:
*solutionId* - UUID of the solution. If not specified, the organization types are retrieved from the default *solutionId*.

DELETE /v1/organization_types/{organizationTypeId}

Deletes an organization type from the solution. The caller must be an authenticated Network Administrator.
**Parameters**:
*solutionId* - ID of the solution. If not specified, the organization type is deleted from the default *solutionId*.
*organizationTypeId* - Required. The organization type to delete.

GET /v1/organization_types/{organizationTypeId}

Retrieves an organization type for the solution. The caller must be an authenticated Network Administrator or Organization Administrator.
**Parameters**:
*solutionId* - ID of the solution. If not specified, the organization type is retrieved from the default *solutionId*.
*organizationTypeId* - Required. The organization type to retrieve.

Search

GET /v1/search/systems

Retrieves organization information for the solution and system users. The caller must be a Network Administrator, Solution Administrator or Organization Administrator.
**Parameters**:
*solutionId* - UUID of the solution for the serviceId.
*serviceId* - Service ID of a system user.

GET /v1/search/users

Retrieves user information for a User ID or User Doc ID (UUID). An authenticated Network Administrator must specify a solution ID; all other authenticated callers can only search within their solution ID. Any user registered with the solution can call this endpoint.
**Parameters**:
*solutionId* - Required for an authenticated Network Administrator, otherwise ignored. UUID of the solution for the userId.
*userId* - User ID.
*userDocId* - User UUID.

GET /v1/search/organizations

Retrieves organization information. Any user registered with the solution can call this endpoint.
**Parameters**:
*solutionId* - Required for an authenticated Network Administrator, otherwise ignored. UUID of the solution.
*organizationName* - Name of the organization; supports partial matching and case-insensitive search within a solution.

Users

PUT /v1/organizations/{organizationId}/users

Creates a new human user UUID (userDocId) for the specified organization.
**Parameters**:
*user* - User ID to create.
*solutionId* - UUID of the solution. *organizationId* - Required. UUID of the organization.

DELETE /v1/organizations/{organizationId}/users/{userDocId}

Deletes the specified human user (userDocId).
**Parameters**:
*solutionId* - UUID of the solution.
*organizationId* - Required. UUID of the organization.
*userDocId* - Required. UUID of the user.

POST /v1/organizations/{organizationId}/users/{userDocId}/roles/{roleId}

Adds a role to the specified human user (userDodId).
**Parameters**:
*solutionId* - UUID of the solution.
*organizationId* - Required. UUID of the organization.
*userDocId* - Required. UUID of the user.
*roleId* - Required. UUID of the role.

DELETE /v1/organizations/{organizationId}/users/{userDocId}/roles/{roleId}

Deletes a role from a user.
**Parameters**:
*solutionId* - UUID of the solution.
*organizationId* - Required. UUID of the organization.
*userDocId* - Required. UUID of the user.
*roleId* - Required. UUID of the role.

Systems

PUT /v1/organizations/{organizationId}/systems

Creates a new System User Service ID.
**Parameters**:
*user* - System user definition.
*solutionId* - UUID of the solution.
*organizationId* - Required. UUID of the organization.

DELETE /v1/organizations/{organizationId}/systems/{systemDocId}

Deletes the specified system user.
**Parameters**:
*solutionId* - UUID of the solution.
*organizationId* - Required. UUID of the organization.
*systemDocId* - Required. UUID of the system user.

POST /v1/organizations/{organizationId}/systems/{systemDocId}/roles/{roleId}

Adds a role to the specified system user.
**Parameters**:
*solutionId* - UUID of the solution.
*organizationId* - Required. UUID of the organization.
*systemDocId* - Required. UUID of the system user.
*roleId* - Required. UUID of the role.

DELETE /v1/organizations/{organizationId}/systems/{systemDocId}/roles/{roleId}

Deletes a role from the specified system user.
**Parameters**:
*solutionId* - UUID of the solution.
*organizationId* - Required. UUID of the organization.
*systemDocId* - Required. UUID of the system user.
*roleId* - Required. UUID of the role.

OAuth

GET /v1/jwks

Retrieves an IAM IBMid idaas.iam.ibm.com public key (OAuth 2.0 JWKS). Any IBM Cloud user can call this endpoint.
**Parameters**:
No parameters.

POST /v1/jwks

Submits an IAM IBMid idaas.iam.ibm.com public key (OAuth 2.0 JWKS). Any IBM Cloud user can call this endpoint.
**Parameters**:
No parameters.

GET /v1/onboarding_jwks

Retrieves public keys for the generated **Onboarding Tokens**. Any IBM Cloud user can call this endpoint.
**Parameters**:
No parameters.

POST /v1/auth/reference_token

System Users only. Requests a **Reference Token** on behalf of another System User, in exchange for the submitted **Onboarding Token**.
**Parameters**:
*onboarding_token* - Required. The **Onboarding Token** to exchange.

GET /v1/auth/introspect

System Users only. Returns information about the submitted **Onboarding Token** in a consumable format.
**Parameters**:
No parameters.

GET /v1/logins

Redirects the caller to the user interface login (OAuth 2.0) for a solution.
**Parameters**:
*username* - Required. User name.
*password* - Required. Password for the user name.
*grant_type* - Required. Select a grant type.
*client_id* - Required. Specify the solutionId value.
*organization_id* - Specify an organization_id if the serviceId is not unique across the solution.

POST /v1/iam/exchange_token/solution/{solutionId}/organization/{organizationId}

Exchanges an IBM Cloud IAM Token (issued by https://iam.ng.bluemix.net/oidc/token) for an **Onboarding Token**.
**Parameters**:
*solutionId* - Required. UUID of the solution.
*organizationId* - Required. UUID of the organization.
*apiusertoken* - Required. IBM Cloud IAM Token returned by the https://iam.ng.bluemix.net/oidc/token endpoint.

POST /v1/iam/exchange_token/apps/{appId}

Application System Users only. Exchanges an IBM Cloud IAM Token (issued by https://iam.ng.bluemix.net/oidc/token) for an **Onboarding Token**.
**Parameters**:
*appId* - Required. Application ID associated with the Service ID.
*apiusertoken* - Required. IBM Cloud IAM Token returned by the https://iam.ng.bluemix.net/oidc/token endpoint.

GET /v1/logout

Logs user out of OAuth 2.0 session.
*returnTo* - Optional URL to return user to following logout.

Applications

PUT /v1/apps

Adds an application (as a system user). The caller must be an authenticated Network Administrator or Service Broker.
**Parameters**:
*application* - The application definition.

GET /v1/apps

Retrieves applications (as system users). The caller must be an authenticated Network Administrator or Service Broker.
**Parameters**:
No parameters.

dt> PUT /v1/apps/{appId}/policy

Creates or updates the policy for the specified application. The caller must be an authenticated Network Administrator or Service Broker.
**Parameters**:
*appId* - The application ID.
*policy* - The IDs of the applications, organizations, users (userDocId), and roles that are subject to the application policy.

GET /v1/apps/{appId}/policy

Retrieves the policy for the specified application. The caller must be an authenticated Network Administrator or Service Broker, or an application System User for the specified {appId}.
**Parameters**:
*appId* - Required. The application ID.

DELETE /v1/apps/{appId}

Deletes the specified application. The caller must be an authenticated Network Administrator or Service Broker.
**Parameters**:
*appId* - Required. The application ID.

GET /v1/apps/{appId}

Retrieves the specified application. The caller must be an authenticated Network Administrator, Service Broker, or application System User for the specified {appId}.
**Parameters**:
*appId* - Required. The application ID.

GET /v1/apps/{appId}/chaincodes

Retrieves the chaincode for the specified application. The caller must be an authenticated Network Administrator or Organization Administrator.
**Parameters**:
*appId* - Required. The application ID.

PUT /v1/apps/{appId}/chaincodes

Updates the chaincode for the specified application. The caller must be an authenticated Network Administrator or Organization Administrator.
**Parameters**:
*appId* - Required. The application ID.
*chaincode* - Required. The application chaincode.

Developer

GET /api-docs.json

Exports the IBM Blockchain APIs as JSON.
**Parameters**:
No parameters.