Understanding the Kaleido API

The Kaleido API is a fully RESTful interface for resource management, chain analytics and event monitoring. All calls are privileged, with endpoints only accessible to administrative users in possession of a valid API key.

This document aims to outline the key API endpoints and the accepted HTTP methods. For the full API specifications, please refer to the Swagger OpenAPI Specification. For a hands on tutorial demonstrating the end-to-end creation of a consortium and environment, refer to the comprehensive API 101 tutorial.

All REST calls target a baseline API URL, with the endpoints below available as extensions to the path. If your consortium is configured against EU or AP, the region must be enumerated. Set your $APIURL accordingly:

  • US - APIURL=https://console.kaleido.io/api/v1
  • EU - APIURL=https://console-eu.kaleido.io/api/v1
  • AP - APIURL=https://console-ap.kaleido.io/api/v1 resolves to Sydney
  • AP - APIURL=https://console-ko.kaleido.io/api/v1 resolves to Seoul

Additionally, headers for authorization and content type must accompany every call, regardless of the method. These headers can be passed in their entirety or set as environment variables. For example:

  • HDR_AUTH="Authorization: Bearer <API key>"
  • HDR_CT="Content-Type: application/json"

/regions

Displays the currently available geographies for resource creation. Requires no qualifier.

GET returns the api and deployment hosts for each of the Kaleido regions.

  • Example query for regions:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/regions" | jq

/consortia

Used to create consortia and/or retrieve consortia details related to the callee’s organization.

POST with a name and optional description in the body of the call to create a new consortium.

  • Example create call:
curl -X POST -d '{"name":"ABCconsortium", "description":"example"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia"

GET returns all consortia details or specific details if a consortia ID is enumerated.

  • Example query for all consortia:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia" | jq
  • Example query for a specified consortia:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}" | jq

To update an existing consortium, specify the consortia ID in the path and PATCH with the desired changes for name and/or description in the body of the call.

  • Example update on an existing consortia:
curl -X PATCH -d '{"name":"XYZconsortium", "description":"example changes"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}" | jq

To remove an existing consortium, specify the consortia ID in the path and call the DELETE method.

  • Example deletion of an existing consortia:
curl -X DELETE -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}" | jq

/invitations

Used to create invitations and/or retrieve a listing of invitations associated with the callee’s organization.

GET returns all invitation history related to the callee’s organization. Alternatively, if a consortia ID is enumerated, the returned data will be scoped to invitations within the specified consortium.

  • Example query for all consortia invitations:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/invitations" | jq
  • Example query for a particular consortium’s invitations:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/invitations" | jq

To create an invitation for a consortium, specify the consortia ID in the path and POST with an email and organization name in the body of the call.

  • Example invite creation:
curl -X POST -d '{"email":"bankadmin@abc.org", "org_name":"BANK A"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/invitations" | jq

To update an existing invitation, specify the consortia and invitation IDs in the path and PATCH with the desired change for the organization name in the body of the call. Note that the initial email cannot be altered.

  • Example invitation update:
curl -X PATCH -d '{"org_name":"Updated Org Name"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/invitations/{invitation_id}" | jq

To rescind an invitation, specify the consortia and invitation IDs in the path and call the DELETE method.

  • Example invitation deletion:
curl -X DELETE -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/invitations/{invitation_id}" | jq

/memberships

Used to create/delete memberships and/or retrieve a listing of memberships associated with the callee’s organization.

GET returns all memberships related to the callee’s organization. Alternatively, if a consortia ID is enumerated, the returned data will be scoped to the memberships within the specified consortium.

  • Example query for all memberships:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/memberships" | jq
  • Example query for memberships within a particular consortium:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/memberships" | jq

To add a new member to a consortium, specify the consortia ID in the path and POST with the new org’s name in the body of the call:

  • Example member creation:
curl -X POST -d '{"org_name":"BANK A"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/memberships" | jq

To update the organizational name for an existing membership within a consortium, specify the consortia and membership IDs in the path and PATCH with the desired org name in the body of the call.

  • Example update on an existing membership:
curl -X PATCH -d '{"org_name":"BANK A ASIA"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/memberships/{membership_id}" | jq

To remove an existing membership from a consortium, specify the consortia and membership IDs in the path and call the DELETE method.

  • Example deletion of an existing membership:
curl -X DELETE -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/memberships/{membership_id}" | jq

/environments

Must be called within the context of a consortium. Used to generate new environments and/or retrieve details about existing domains. Environments inherit the membership list of the consortium.

GET returns all existing environments within the context of a consortium. Alternatively, if an environment ID is enumerated, the returned data will be scoped to the specified environment.

  • Example query for all environments within a consortium:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments" | jq
  • Example query for a specific environment within a consortium:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}" | jq

To generate a new environment, specify the consortia ID in the path and POST with a provider, consensus type and name in the body of the call.

  • Example environment creation with Geth + PoA configuration:
curl -X POST -d '{"provider":"geth", "consensus_type":"poa", "name":"Sample Environment"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments" | jq

To update an environment, specify the consortia and environment IDs in the path and PATCH with the desired name and/or description in the body of the call.

  • Example environment update:
curl -X PATCH -d '{"name":"New Environment Name", "description":"example change"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environment/{environment_id}" | jq

To quiesce a live environment, specify the consortia and environment IDs in the path and PATCH with "state":"paused" in the body of the call.

  • Example environment quiesce:
curl -X PATCH -d '{"state":"paused"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}" | jq

To restart a quiesced environment, specify the consortia and environment IDs in the path and PATCH with "state":"live" in the body of the call. Note that environments are configured, by default, to quiesce after 24 hours of inactivity.

  • Example environment restart:
curl -X PATCH -d '{"state":"live"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}" | jq

To remove an environment, specify the consortia and environment IDs in the path and call the DELETE method.

  • Example deletion of an existing environment:
curl -X DELETE -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}" | jq

/configurations

Must be called within the context of an environment. Used to generate/update/delete configurations and/or retrieve details about existing configurations. The available configuration objects are: kms for auditable decryption of node key files, opsmetric for realtime streaming of node logs to AWS Cloudwatch, networking for private connections into a Kaleido node, and backup for on demand backups of a targeted node’s filesystem. Configurations are standalone objects and must be referenced as part of the node creation call in order to enable the service(s).

GET returns all existing configurations for memberships associated with your Kaleido Organization. Alternatively, if a configuration ID is enumerated, the returned data will be scoped to the specified object.

  • Example query for all configurations within an environment:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments{environment_id}/configurations" | jq
  • Example query for a specific configuration within an environment:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/configurations{configuration_id}" | jq

To create a new kms configuration, specify the consortia and environment IDs in the path and POST with the name, type, membership ID and kms details in the body of the call. The details parameter encompasses the following fields:

  • “provider” - the cloud provider supporting the key management service. Enumerated with aws.
  • “region” - the region within the cloud provider containing the KMS instance. For example, us-east-1.
  • “api_key” - ID of the IAM user with access to the encryption key.
  • “api_secret” - the secret access key associated with the IAM user ID.
  • “master_key” - the alias or Amazon Resource Name (ARN) for the encryption key. For example, alias/ExampleName or arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab.

  • Example kms creation:
curl -X POST -d '{"name":"KMSEXAMPLE", "type":"kms", "membership_id":"abcde12345", "details":{"provider":"aws", "region":"us-east-1", "api_key":"12345SHCM5AFUTCXXXXX", "api_secret":"abcdeho4qPkjVw2HNLmxRCJXwaStUj3Abme12345", "master_key":"alias/ExampleName"}}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/u0n84abcde/environments/u0otp12345/configurations" | jq

A kms_id will be returned upon a successful kms creation. The ID can then be passed as a parameter on the node creation call to enable KMS.

To create a new opsmetric configuration, specify the consortia and environment IDs in path and POST with the name, type, membership ID and opsmetric details in the body of the call. The details parameter encompasses the following fields:

  • “provider” - the cloud provider supporting the Ops Metrics target. Enumerated with aws.
  • “region” - the region within the cloud provider containing the Ops Metrics target. For example, us-east-2.
  • “user_id” - ID of an IAM user or role with the following Cloudwatch permissions: CreateLogStream, DescribeLogGroups, DescribeLogStreams, CreateLogGroup and PutLogEvents.
  • “user_secret” - the secret access key associated with the IAM user or role containing the above permissions.
  • “group” - name of the logging group in Cloudwatch that will receive the logs

  • Example opsmetric creation:
curl -X POST -d '{"name":"METRICSEXAMPLE", "type":"opsmetric", "membership_id":"abcde12345", "details":{"provider":"aws", "region":"us-east-2", "user_id":"12345SHCM5AFUTCXXXXX", "user_secret":"abcdeho4qPkjVw2HNLmxRCJXwaStUj3Abme12345", "group":"ExampleLoggingGroupName"}}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/u0n84abcde/environments/u0otp12345/configurations" | jq

An opsmetric_id will be returned upon a successful opsmetric creation. The ID can then be passed as a parameter on the node creation call to enable Ops Metrics.

To create a new networking configuration, specify the consortia and environment IDs in the path and POST with the name, type, membership ID and networking details in the body of the call. The details parameter encompasses the following fields:

  • “allow_private” - expressed as a boolean, whether or not the node is privately routable via AWS PrivateLink. Defaults to false
  • “allow_public” - expressed as a boolean, whether or not the node is publicly routable. Defaults to true

NOTE: Public and private ingresses are not mutually exclusive configurations and you have the option of enabling both to create a hybrid connection layer for the node.

  • Example networking creation for private ingress only:
# the boolean constants are expressed WITHOUT ""
# the public ingress must be defined as false for private only config
curl -X POST -d '{"name":"PRIVATECONFIG", "type":"networking", "membership_id":"abcde12345", "details":{"allow_private":true, "allow_public":false}}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/u0n84abcde/environments/u0otp12345/configurations" | jq
  • Example networking creation for public and private ingresses:
# the boolean constant is expressed WITHOUT ""
# the public ingress defaults to true so it does not need to be expressed
curl -X POST -d '{"name":"PRIVATECONFIG", "type":"networking", "membership_id":"abcde12345", "details":{"allow_private":true}}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/u0n84abcde/environments/u0otp12345/configurations" | jq

A networking_id will be returned upon a successful networking creation. The ID can then be passed as a parameter on the node creation call to enable the desired connection layer.

To create a new backup configuration, specify the consortia and environment IDs in the path and POST with the name, type, membership ID and backup details in the body of the call. The details parameter encompasses the following fields:

  • “provider” - the cloud provider supporting backup storage. Enumerated with aws.
  • “region” - The region within the cloud provider containing the backup storage target. For example, us-east-2.
  • “user_id” - ID of the IAM user or role created with S3 write permissions
  • “user_secret” - Secret of the IAM user or role created with S3 write permissions
  • “bucket” - Name of the S3 bucket to store backups

  • Example backup creation:
curl -X POST -d '{"name":"NODE1BACKUP", "type":"backup", "membership_id":"abcde12345", "details":{"provider":"aws", "region":"us-east-2", "user_id":"12345SHCM5AFUTCXXXXX", "user_secret":"abcdeho4qPkjVw2HNLmxRCJXwaStUj3Abme12345", "bucket":"myS3bucket"}}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/u0n84abcde/environments/u0otp12345/configurations" | jq

A backup_id will be returned upon a successful backup creation. The ID can then be passed as a parameter on the node creation call to integrate the node with the specified S3 bucket. See the /nodes section for details on invoking the backup.

To remove a configuration object, specify the consortia, environment and resource IDs in the path and call the DELETE method. Note that a configuration CANNOT be deleted if it is in active use by a node. To remove a running configuration, you must first delete the node.

  • Example configuration deletion:
curl -X DELETE -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/configurations/{configuration_id}" | jq

To update the name of a configuration, specify the consortia, environment and configuration IDs in the path and PATCH with the desired name in the body of the call.

  • Example configuration update:
curl -X PATCH -d '{"name":"NewName"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/configurations/{configuration_id}" | jq

/nodes

Must be called within the context of an environment. Used to generate/update/backup/delete nodes and/or retrieve details about existing nodes. Node runtimes inherit the configuration parameters of the environment.

GET returns all existing nodes within a specified environment. Alternatively, if a node ID is enumerated, the returned data will be scoped to the specified node.

  • Example query for all nodes within an environment:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/nodes" | jq
  • Example query for a specific node within an environment:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/nodes/{node_id}" | jq

To create a new node, specify the consortia and environment IDs in the path and POST with a membership ID, name and optional configuration ID in the body of the call. If the node is to contain one or more configurations, the configuration object(s) must exist in the environment and contain the same membership ID that is being passed to the node. For example, to create a KMS-enabled node against a membership ID of abcde12345, a kms configuration object with a membership ID of abcde12345 must already exist in the environment. Please refer to the previous /configurations section for details on creating configurations.

  • Example node creation with no configurations:
curl -X POST -d '{"membership_id":"abcde12345", "name":"BANK A node"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/nodes" | jq
  • Example node creation with KMS and Ops Metrics enabled:
curl -X POST -d '{"membership_id":"abcde12345", "name":"BANK A node", "kms_id":"xyz123fghi", "opsmetric_id":"def456jklm"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/nodes" | jq

To backup a node, specify the consortia, environment and node IDs in the path and call the PUT method against the /backup endpoint. Backup will only work against nodes that have been provisioned with a backup configuration.

  • Example node backup:
curl -X PUT -d '{}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/nodes/{node_id}/backup" | jq

To update the name of an existing node, specify the consortia and environment IDs in the path and PATCH with the desired name in the body of the call.

  • Example node name update:
curl -X PATCH -d '{"name":"NewName"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/nodes/{node_id}" | jq

To remove a node, specify the consortia, environment and node IDs in the path and call the DELETE method.

  • Example node deletion:
curl -X DELETE -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/nodes/{node_id}" | jq

/appcreds

Must be called within the context of an environment. Used to generate basic access authentication credentials for application consumption. The returned password is ephemeral and does not get stored by the Kaleido backend.

GET returns all active sets of authentication credentials within the targeted environment. Only the username of the credentials is exposed.

  • Example query for all active credentials within an environment:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/appcreds" | jq

To create a new set of application credentials, specify the consortia and environment IDs in the path and POST with a membership ID and optional name in the body of the call.

  • Example application credentials creation:
curl -X POST -d '{"membership_id":"abcde12345", "name":"Bank A creds"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/appcreds" | jq

To change the name of an existing set of credentials, specify the consortia, environment and appcreds IDs in the path and PATCH with the desired name in the body of the call.

  • Example credentials name update:
curl -X PATCH -d '{"name":"new creds name"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/appcreds/{appcreds_id}" | jq

To delete a set of credentials, specify the consortia, environment and appcreds IDs in the path and call the DELETE method.

  • Example credential deletion:
curl -X DELETE -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/appcreds/{appcreds_id}" | jq

/fundaccount

Must be called within the context of an environment in order to leverage a pre-funded account. Used to add Ether to an internal user account or an external account.

To add funds, specify the the consortia and environment IDs in the path and POST with the account address and requested amount in the body of the call.

Example funding request:

curl -X POST -d '{"account":"0x51D91D3128252728a37131713c8d98724BDF744E", "amount":"1000000"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/eth/fundaccount" | jq

/apikeys

Can be used to create/delete admin credentials, view active keys for the callee’s organization and/or update the name of an existing key.

To generate a new key, POST with a name and your organization ID in the body of the call.

  • Example key creation:
curl -X POST -d '{"name":"new api key", "org_id":"abcde12345"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/apikeys" | jq

GET returns a listing of all valid keys associated with the targeted organization. Alternatively, if an APIKEY ID is enumerated, the returned data will be scoped to the specified key. Only the key ID, org ID and key name are displayed.

  • Example query for all API keys:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/apikeys"
  • Example query for a specific key:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/apikeys/{apikey_id}" | jq

To change the name of an existing key, specify the key ID in the path and PATCH with the desired name in the body of the call.

  • Example API key update:
curl -X PATCH -d '{"name":"Updated Name"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/apikeys/{apikey_id}" | jq

To delete an API key, specify the key ID in the path and call the DELETE method.

  • Example key deletion:
curl -X DELETE -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/apikeys/{apikey_id}" | jq

/authtoken

Used to generate a system JSON Web Token (JWT). This JWT affords the same permissions as the organizational API key, but offers increased performance for resource management calls. Additionally, the token expires after an hour allowing for admin credential lifecycles to be implemented via the API. An existing organizational API key is required for JWT generation.

To create an authorization token, POST to the /authoken endpoint with the existing API key in the body of the call.

  • Example token generation:
curl -X POST -d '{"apikey":"zzue1mje6m-8Nu7XihDWiuuumolA9jHURMARO3k9t1/+RpTckseI9k="}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/authtoken" | jq

The system JWT can then be used as an alternative to the API key in the authorization header. For example:

HDR_AUTH="Authorization: Bearer <JWT>"

/releases

Platform API used to display current and historical network releases.

Calling GET against the /releases endpoint with no qualifier will return a listing of all releases. Alternatively, if a release ID is enumerated, the returned data will be scoped to the specified release.

Releases are distinguished through a unique resource ID, with each containing fields for: provider, version, description, images, revision and created_at. Call this endpoint prior to an environmental upgrade and ascertain the desired release ID.

  • Example query for all releases:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/releases" | jq
  • Example query for a specific release:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/releases/{release_id}" | jq

/upgrade

Used to upgrade an environment to an enumerated release ID. To upgrade, specify the consortia and environment IDs in the path and POST with the desired release_id in the body of the call.

Example environmental upgrade:

curl -X POST -d '{"release_id":"u0wrjlr6ba"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/upgrade" | jq

/transactions

Ledger API used to retrieve transactional data within a specified environment.

Calling GET against the base /transactions API returns a listing of all transactions within the environment. Alternatively, if a transaction hash is enumerated, the returned data will be scoped to the specified transaction.

  • Example query for all transactions:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/transactions" | jq
  • Example query for a specific transaction:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/transactions/{tx_hash}" | jq

/blocks

Ledger API used to retrieve block data within a specified environment.

Calling GET against the base /blocks API returns the 25 most recent blocks. Alternatively, the API can be extended to specify individual blocks or a grouping of blocks.

  • Example query for 25 most recent blocks:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/blocks" | jq
  • Example query for the first block:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/blocks/0" | jq
  • Example query for the latest block:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/blocks?count=1" | jq

The start and limit parameters allow for a subset of blocks to be specified.

  • Example query for the first 10 blocks:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/blocks?start=9&limit=10" | jq

/contracts

Ledger API used to retrieve contract data within a specified environment.

Calling GET against the base /contracts API returns a listing of all callable addresses in the environment. Alternatively, the API can be extended to target a specific contract address.

  • Example query for all callable contracts:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/contracts" | jq
  • Example query for a specific contract:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/contracts/{contract_address}" | jq

/addresses

Ledger API used to retrieve data for contracts and/or Ethereum accounts within a specified environment.

Any call against the /addresses endpoint requires a qualifying address as an extension to the API.

  • Example query for a contract address:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/addresses/{contract_address}" | jq
  • Example query for a user account:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/addresses/{account_address}" | jq

/stats

Ledger API used to retrieve high-level block and transaction data within a specified environment.

Any call against the /stats endpoint requires a valid ISO timestamp as an extension to the API.

  • Example statistical query:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/ledger/{consortia_id}/{environment_id}/stats/{ISO_timestamp}" | jq

/audit

A lifecycle API used to retrieve organizational or consortia events.

GET returns a listing of all events related to the callee’s organization. If a consortium is enumerated on the API, the returned data will be scoped to events within the specified consortium.

  • Example audit for all organizational events:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/audit" | jq
  • Example audit for a particular consortium’s events:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/audit/{consortia_ID}" | jq

/plans

Displays the network resource limitations. Calling the /plans endpoint with no qualifier will return a listing of all available Kaleido plans.

To view the network resource limitations associated with your organization, supply your plan ID or default in the path. All Kaleido plans currently begin at default status.

GET will return the limitations for roles, consortia, memberships, environments, nodes and credentials.

  • Example query for all plans:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/plans" | jq
  • Example query for default plan:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/plans/default" | jq
  • Example query for a specific plan:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/plans/{plan_id}" | jq

/orgs

Used to display the subscriptions for your organization and/or update an existing subscription.

GET returns a listing of all subscriptions your org has access to. Alternatively, if an org ID is enumerated, the returned data will be scoped to the specified org.

  • Example query for all subscriptions:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/orgs" | jq
  • Example query for a specific subscription:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/orgs/{org_id}" | jq

To change the configuration of an existing subscription, specify the org ID in the path and PATCH with the desired change(s) to name and/or delegate email:

  • Example subscription update:
curl -X PATCH -d '{"name":"Updated Name", "delegate":"email@abc.org"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/orgs/{org_id}" | jq

The following is an advanced configuration and requires familiarity with Amazon Cognito and its available authentication protocols. This is only necessary for organizations that want full control over their user pools and identity providers.

The /orgs endpoint can also be used to generate an enterprise organization with AWS Cognito integration, allowing you to manage all user logins through a User Pool and Identity Provider of your choice. Note that the creation of an enterprise org is contingent upon the existence of a standard Kaleido org, which is automatically provisioned upon the generation of a Kaleido account. Enterprise orgs are detached from the founding Kaleido org on the first successful sign in and maintain no correlation with other orgs once they exit “draft” status (i.e. the org has been successfully accessed via the configured User Pool and Identity Provider schema). The enterprise org is only accessible through its unique URL and Identity Provider orchestration, or via an APIKEY generated within the Enterprise Org. Refer to the /docs/docs/enterprise-orgs/ topic for further details on Cognito User Pools and authentication protocols.

To generate a new Enterprise Organization POST to the appropriate $APIURL with the following fields in the body of the call:

  • “name” - The name for your Enterprise Organization. This is an arbitrary string that does not derive from your Cognito resources.
  • “type” - The type of organization. Enumerate enterprise_cognito.
  • “cognito_region” - The region in AWS containing the Cognito instance you will be using for the Enterprise Org. For example, us-east-2.
  • “cognito_domain” - The Cognito domain name such as mydomain.auth.us-east-2.amazoncognito.com
  • “cognito_user_pool_id” - The ID in AWS Cognito of the user pool allowed to access the Enterprise Org
  • “cognito_client_id” - The Client ID of the App client created for the targeted Cognito User Pool
  • “cognito_client_secret” - The Client secret of the App client created for the targeted Cognito User Pool

  • Example Enterprise Org creation:
curl -X POST -H "$HDR_AUTH" -H "$HDR_CT" -d '{"name":"Example Enterprise Org", "type":"enterprise_cognito", "cognito_domain":"us-east-2", "cognito_user_pool_id":"us-east-2_abcde1234", "cognito_client_id":"12345vmose9pgn4591ol7abcde", "cognito_client_secret":"15id1kboo63t3r9fa9frne0ehlfbqsmt823it496XXXXXXXXX"}' "$APIURL/orgs" | jq

Returns the Enterprise Org ID and the callback URL. The callback URL needs to be injected into your AWS Cognito application client as explained here prior to attempting a login. The org is then accessible through the standard Kaleido URL, with /e/{enterprise_org_id} applied as a suffix. For example, https://console.kaleido.io/e/abcde12345.

/roles

Used to display the current roles for an existing organization and/or update the list. All roles currently default to admin status.

GET returns a listing of all roles (i.e. admins) for a given organization.

  • Example query for an organization’s roles:
curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/orgs/{org_id}/roles" | jq

To add a new role to an organization, specify the org ID in the path and POST with the email of the new admin in the body of the call.

  • Example role addition:
curl -X POST -d '{"email":"newadmin@abc.org"}' -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/orgs/{org_id}/roles" | jq

To remove a role from an organization, specify the org and role IDs in the path and call the DELETE method.

  • Example role deletion:
curl -X DELETE -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/orgs/{org_id}/roles/{role_id}" | jq