ChainFront Cloud Service REST API (1.0.4)

Download OpenAPI specification:Download

Bringing security and usability to enterprise blockchain applications

Introduction

The ChainFront Cloud Services API enables developers to quickly and easily integrate their solutions with blockchain networks. The API endpoints support connecting to the Stellar, Ripple (XRP), Ethereum, and Bitcoin networks. By using ChainFront, you provide your users with a secure and easy way to approve transactions without the need for them to manage their own private keys. The private keys are created within the secure environment provided by ChainFront and never leave this environment, nor are they ever viewable. You can easily create accounts, transfer tokens, and invoke contracts, all with the benefit of requiring multi-factor authentication for any transaction signer.

The current version of the API is v1.

Getting Started

The ChainFront Cloud Service API is a RESTful API. It allows you to create accounts, configure multi-factor transaction approval methods, create blockchain addresses, create and sign transactions, and submit transactions to a blockchain network.

All production API requests are made to:

https://api.chainfront.io/api/v1

There is also a testing sandbox to use when developing and testing applications, with requests being made to:

https://sandbox.chainfront.io/api/v1

All requests to the ChainFront REST API are served over HTTPS. Unencrypted HTTP is not supported.

The API is available to ChainFront customers and integration partners and all organizations must acquire valid credentials prior to using the web services. All API endpoints require authentication. Please see the Security section below for additional information.

Security

Production Environments

For production usage, the ChainFront REST API uses the OAuth 2.0 protocol to authorize calls.

When you integrate with ChainFront, you will receive a set of OAuth client ID and secret credentials for your app for both the sandbox and production environments. You pass these credentials via the Authorization header of the get_access_token request.

In exchange for these credentials, the ChainFront authorization server issues a bearer access token that you use for authorization when you make REST API requests. A bearer token enables you to complete actions on behalf and with the approval of the resource owner.

Sandbox Environments

In the sandbox environment, for ease of testing you may instead opt to use an API key via HTTP Basic Authentication.

To authenticate using an API key, use HTTP basic auth with the username set to the API key's name and the password set to the API key's secret.

Most client software provides a mechanism for supplying a user name and password and will build the required authentication header automatically.

In the case where you need to manually construct and send a basic auth header with your API key, perform the following steps:

  1. Build a string of the form apiKeyName:apiKeySecret
  2. Base64 encode the string
  3. Supply an "Authorization" header with content "Basic " followed by the encoded string. For example, the string "apiKeyName:apiKeySecret" encodes to "YXBpS2V5TmFtZTphcGlLZXlTZWNyZXQ=" in base64, so you would add the following HTTP header to your request: Authorization: Basic YXBpS2V5TmFtZTphcGlLZXlTZWNyZXQ=

In addition, you will need to pass a X-CUSTOMER-ID header with all requests. The value of this header will be provided to you when you sign up.

Authorization

ApiKey

Security scheme type: HTTP
HTTP Authorization Scheme basic

OAuth2

Security scheme type: OAuth2
authorizationCode OAuth Flow
Authorization URL: https://sandbox.chainfront.io/oauth/authorize
Token URL: https://sandbox.chainfront.io/oauth/token
Scopes:
  • read:accounts -

    Grants read access to accounts

  • write:accounts -

    Grants write access to accounts

  • read:stellar_accounts -

    Grants access to read Stellar accounts

  • write:stellar_accounts -

    Grants access to create Stellar accounts

  • write:stellar_txs -

    Grants access to create Stellar transactions and payments

  • read:ripple_accounts -

    Grants access to read Ripple accounts

  • write:ripple_accounts -

    Grants access to create Ripple accounts

  • write:ripple_txs -

    Grants access to create Ripple transactions and payments

  • read:ethereum_accounts -

    Grants access to read Ethereum accounts

  • write:ethereum_accounts -

    Grants access to create Ethereum accounts

  • write:ethereum_txs -

    Grants access to create Ethereum transactions

  • read:ethereum_contracts -

    Grants access to read Ethereum contracts

  • write:ethereum_contracts -

    Grants access to create Ethereum contracts

  • execute:ethereum_contracts -

    Grants access to execute Ethereum contracts

  • read:bitcoin_accounts -

    Grants access to read Bitcoin accounts

  • write:bitcoin_accounts -

    Grants access to create Bitcoin accounts

  • write:bitcoin_txs -

    Grants access to create Bitcoin transactions

Multi-Factor Transaction Approvals

In a traditional blockchain security architecture, users are responsible for keeping a private key secure. In a traditional enterprise application, users are accustomed to password recovery, rolling passwords, and generally are not expected to manage their own password backups. ChainFront blends these approaches by abstracting the private key away from the user, in exchange for the user presenting a multi-factor approval via a device they have proved they own.

Each account can be configured with a transaction approval method. For every transaction in which the account is a signer, the approval method indicates how the user is to approve the transaction.

  • AUTHY_PUSH: sends a push approval request to the registered Authy id.
  • CHAINFRONT_TOTP: using ChainFront UIs, the user will have to scan a QR Code with Google Authenticator or Authy, and will be prompted to enter their TOTP code.
  • APP_TOTP: Your app will need to collect a TOTP code from the user and pass it in the X-TOTP-Code header.
  • IMPLICIT: No approval will be required for transactions with this account. Use this flow when your application handles all security related to account identity.
Tx Approval Method Requires User Approval Approval Type Registration Flow Who Collects Approval Supports Additional Approvers
AUTHY_PUSH yes Push Notification SMS prompt to install Authy ChainFront yes
CHAINFRONT_TOTP yes TOTP Code SMS code ChainFront yes
APP_TOTP yes TOTP Code SMS code Your App no
IMPLICIT no None None None no

Supported Data Formats

The ChainFront APIs use JSON as the default format.

Ensure you set the following HTTP headers in order for JSON to be properly processed:

Content-Type: application/json

Accept: application/json

Software Development Kits (SDKs)

While you can use ChainFront APIs by making direct HTTP requests, we provide client library code for all our APIs that make it easier to access them from your favorite languages.

Currently we offer Java, Javascript, Go, and Python client libraries. SDKs for other languages can be generated by using OpenAPI tooling.

To obtain the latest SDKs please contact us at info@chainfront.io.

Examples

In this example we show how to onboard a user, configure multi-factor transaction approval, and submit a transaction to the Stellar blockchain. Note that in this example we are using Authy push approvals as our MFA method. Also for simplicity we're using API keys rather than OAuth 2 flows.

Step 1: Create User Account

curl -X POST \
  https://sandbox.chainfront.io/api/v1/accounts \
  -H 'accept: application/json' \
  -H 'authorization: Basic Y2ZhZG1pbkB......' \  
  -H 'content-type: application/json' \  
  -H 'x-customer-id: MY_CUSTOMER_ID' \
  -d '{
    "userName": "user01",
    "email": "user@mycompany.com",
    "phone": "555-555-5555",
    "txApprovalMethod": "AUTHY_PUSH"
}'

This will create an account for user 'user01' in a state of 'PENDING', and send an SMS to the user instructing them how to enable Authy on their phone. Once the user has enabled Authy, the account will move to a state of 'ACTIVE'.

Take note of the 'cfAccountid' value returned in the response body, as this will be used in downstream calls to identify the user. We're assuming that the returned id is '1000' for the remaining steps.

Step 2: Create a Stellar Address

curl -X POST \
  https://sandbox.chainfront.io/api/v1/accounts/1000/stellar \
  -H 'accept: application/json' \
  -H 'authorization: Basic Y2ZhZG1pbkB.......' \  
  -H 'content-type: application/json' \  
  -H 'x-customer-id: MY_CUSTOMER_ID' \
  -d '{
}'

This call will create a Stellar address for the user. Since we're in a test environment, the account will also be funded with some fake XLMs.

Step 3: Create a Payment Transaction

Now you'd like to send XLM to another ChainFront user.

First, generate a unique "idempotency key" to prevent this payment from being applied more than once.

export IDEMPOTENCY_KEY=`uuidgen -r`

Now you can create a payment transaction using that key:

curl -X POST \
  https://sandbox.chainfront.io/api/v1/stellar/transactions/payments \
  -H 'accept: application/json' \
  -H 'authorization: Basic Y2ZhZG1pbkB.......' \  
  -H 'content-type: application/json' \  
  -H 'x-customer-id: MY_CUSTOMER_ID' \  
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
  -d '{
    "sourceCfAccountIdentifier": { "type" : "ID", "identifier":"1000" },
    "destinationCfAccountIdentifier": { "type" : "ID", "identifier":"1001" },
    "amount": "50",
    "assetCode": "native",
    "memo": "This is a test memo"
}'

This will request approval from user id 1000, and once granted, will create, sign, and submit a transaction to Stellar to send 50 XLM to user 1001.

Step 4: Check Account Balances

To verify that our payment transaction was successfully applied to the ledger, we'll invoke the ChainFront APIs to check the Stellar account balances.

curl -X GET \
  https://sandbox.chainfront.io/api/v1/accounts/1000/stellar \
  -H 'accept: application/json' \
  -H 'authorization: Basic Y2ZhZG1pbkB.......' \  
  -H 'content-type: application/json' \  
  -H 'x-customer-id: MY_CUSTOMER_ID' 

Response:

{
    "cfAccountId": 1000,
    "address": "GCFZ5N7NRKPQK5ZCK3CVUFA4ATXXE6HIPXBXOIMDAGXKFDTEI26GM5R3",
    "balances": [
        {
            "assetType": "native",
            "assetCode": "XLM",
            "amount": "9949.99995"
        }
    ],
    "blacklistAddresses": [],
    "whitelistAddresses": [],
    "createdDate": "2018-10-23T03:35:05.479158Z",
    "lastModifiedDate": "2018-10-23T03:35:05.479158Z"
}

For account 1001:

curl -X GET \
  https://sandbox.chainfront.io/api/v1/accounts/1001/stellar \
  -H 'accept: application/json' \
  -H 'authorization: Basic Y2ZhZG1pbkB.......' \  
  -H 'content-type: application/json' \  
  -H 'x-customer-id: MY_CUSTOMER_ID' 

Response:

{
    "cfAccountId": 1001,
    "address": "GBH4TZYZ4IRCPO44CBOLFUHULU2WGALXTAVESQA6432MBJMABBB4GIYI",
    "balances": [
        {
            "assetType": "native",
            "assetCode": "XLM",
            "amount": "10050.0"
        }
    ],
    "blacklistAddresses": [],
    "whitelistAddresses": [],
    "createdDate": "2018-10-23T03:35:05.479158Z",
    "lastModifiedDate": "2018-10-23T03:35:05.479158Z"
}

We see that the payment of 50 XLM was successful, and the required Stellar transaction fees were also deducted from the source account.

Account Service

The ChainFront account services support creating, reading, and updating ChainFront accounts.

List accounts

Returns a paginated list of all accounts.

Authorizations:
OAuth2 (read:accounts) ApiKey
query Parameters
pageNumber
integer <int32>

Page number

pageSize
integer <int32>

Number of accounts returned

Responses

200

A list of accounts

400

Invalid request

401

Invalid or missing credentials

403

User not authorized to perform this operation

get /api/v1/accounts
https://sandbox.chainfront.io/api/v1/accounts

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Create account

Create a new account

Authorizations:
OAuth2 (write:accountsread:accounts) ApiKey
Request Body schema: application/json

Account to create.

userName
required
string

The username of the account.

email
required
string

The email address of the account.

phone
required
string

The phone number of the account.

txApprovalMethod
required
string
Enum:"AUTHY_PUSH" "CHAINFRONT_TOTP" "APP_TOTP" "IMPLICIT"

The transaction approval method for this account. For every transaction where this account is a signer, the approval method indicates how the user is to approve the transaction. [AUTHY_PUSH]: sends a push approval request to the registered Authy id. [CHAINFRONT_TOTP]: using ChainFront UIs, the user will have to scan a QR Code with Google Authenticator, and will be prompted to enter their TOTP code. [APP_TOTP]: Your app will need to collect the TOTP code from the user and pass it in the X-TOTP-Code header. [IMPLICIT]: No approval will be required for transactions with this account. Use this flow when your application handles all security related to account identity.

verification
object (VerificationInfo)

Responses

201

Account created successfully

400

Invalid request

401

Invalid or missing credentials

403

User not authorized to perform this operation

post /api/v1/accounts
https://sandbox.chainfront.io/api/v1/accounts

Request samples

application/json
Copy
Expand all Collapse all
{
  • "userName": "string",
  • "email": "string",
  • "phone": "string",
  • "txApprovalMethod": "AUTHY_PUSH",
  • "verification":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "cfAccountId": 0,
  • "userName": "string",
  • "email": "string",
  • "phone": "string",
  • "txApprovalMethod": "AUTHY_PUSH",
  • "status": "ACTIVE",
  • "verification":
    {
    },
  • "createdDate": "2019-05-06T17:47:54Z",
  • "lastModifiedDate": "2019-05-06T17:47:54Z"
}

Search for accounts

Search for accounts matching a given set of criteria. This uses a simple query language.

To search for a user by email: /accounts/search?query=email:john.doe@company.com.

To search by user name: /accounts/search?query=userName:johndoe.

To search by phone number: /accounts/search?query=phone:555-555-5555.

Authorizations:
OAuth2 (read:accounts) ApiKey
query Parameters
query
string

Search query string

Responses

200

A list of accounts

400

Invalid request

401

Invalid or missing credentials

403

User not authorized to perform this operation

get /api/v1/accounts/search
https://sandbox.chainfront.io/api/v1/accounts/search

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get account

Returns account details for the given account identifier

Authorizations:
OAuth2 (read:accounts) ApiKey
path Parameters
cfAccountId
required
integer <int64>

Account identifier

Responses

200

Account details

400

Invalid request

401

Invalid or missing credentials

403

User not authorized to perform this operation

get /api/v1/accounts/{cfAccountId}
https://sandbox.chainfront.io/api/v1/accounts/{cfAccountId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "cfAccountId": 0,
  • "userName": "string",
  • "email": "string",
  • "phone": "string",
  • "txApprovalMethod": "AUTHY_PUSH",
  • "status": "ACTIVE",
  • "verification":
    {
    },
  • "createdDate": "2019-05-06T17:47:54Z",
  • "lastModifiedDate": "2019-05-06T17:47:54Z"
}

Verify an account

Verify a new account by checking an SMS code sent to a user.

Authorizations:
OAuth2 (write:accountsread:accounts) ApiKey
path Parameters
cfAccountId
required
integer <int64>

The ChainFront account id.

Request Body schema: application/json

The phone verification code.

code
string

Responses

201

Account verified successfully

400

Invalid request

401 </