title: Whiteflag API v1.0.0-beta.2 language_tabs:

• shell: Shell
• http: HTTP
• javascript: JavaScript
• ruby: Ruby
• python: Python
• php: PHP
• java: Java
• go: Go toc_footers: [] includes: [] search: true highlight_theme: darkula headingLevel: 2

Whiteflag API v1.0.0-beta.2

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

This Whiteflag Application Programming Interface (API) is a Node.js software implementation of the API layer that provides an interface with the Whiteflag messaging network on one or more underlying blockchains. It acts as a message transceiver between one or more blockchains and one or more end-user applications.

This API is a so called Minumum Viable Product (MVP), which means that it only supports the core features of the Whiteflag protocol for development and testing purposes. As such, it serves as the reference implementation of the Whiteflag protocol, but it is not designed and tested for secure usage and performance in a production environment.

This definition documents the API in OpenAPI format.

Two methods are available for interaction with the API: 1. a REST API for originators to provide Whiteflag message to be sent on the blockchain, and 2. a socket.io web socket variant available on /socket for clients to listen for incoming Whiteflag messages from a blockchain. A running API has a webpage with embedded socket listener available on /listen and the documented source code at /docs.

All response bodies are structured as {meta, data, errors}, based on the JSON API Specification, which has been used as a guideline (and as a guideline only).

Base URLs:

• http://{hostname}:{port}/

  • hostname - Configurable hostname Default: localhost

  • port - Configurable port number Default: 5746

Authentication

• HTTP Authentication, scheme: basic The API may be configured to use basic HTTP authentication, as specified in RFC 7617. It uses the standard Authorization field in the HTTP header as follows: Authorization: Basic <credentials>, where the credentials are the base64 encoded username and password joined by a single colon: <username>:<password>

Messages

Endpoints for operations on Whiteflag messages, such as retrieval, sending, encoding, decoding and validation.

getMessages

GET /messages

Returns an array with all incoming and outgoing messages from the primary datastore. The operation accepts MetaHeader fields as optional query parameters. This operation may be disabled in the configuration.

Parameters

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": [
    {
      "MetaHeader": null,
      "MessageHeader": null,
      "MessageBody": null
    }
  ]
}

Responses

Response Schema

sendMessage

POST /messages/send

Transmits a Whiteflag message on a blockchain and returns the result. This operation may be disabled in the configuration.

Body parameter

{
  "MetaHeader": null,
  "MessageHeader": null,
  "MessageBody": null
}

Parameters

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": {
    "MetaHeader": null,
    "MessageHeader": null,
    "MessageBody": null
  }
}

Responses

Response Schema

receiveMessage

POST /messages/receive

Accepts a Whiteflag message as if received from a blockchain. This may be done for simulation of incoming messages or if a direct connection with a blockchain node is not possible. Typically only used for testing. This operation may be disabled in the configuration.

Body parameter

{
  "MetaHeader": null
}

Parameters

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": {
    "MetaHeader": null,
    "MessageHeader": null,
    "MessageBody": null
  }
}

Responses

Response Schema

encodeMessage

POST /messages/encode

Encodes a Whiteflag message and returns the result. Typically used for validation and testing, because this is automatically done for outgoing messages. This operation may be disabled in the configuration.

Body parameter

{
  "MetaHeader": null,
  "MessageHeader": null,
  "MessageBody": null
}

Parameters

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": {
    "MetaHeader": null,
    "MessageHeader": null,
    "MessageBody": null
  }
}

Responses

Response Schema

decodeMessage

POST /messages/decode

Decodes a Whiteflag message and returns the result. Typically used for validation and testing, because this is automatically done for incoming messages. This operation may be disabled in the configuration.

Body parameter

{
  "MetaHeader": null
}

Parameters

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": {
    "MetaHeader": null,
    "MessageHeader": null,
    "MessageBody": null
  }
}

Responses

Response Schema

validateMessage

POST /messages/validate

Validates the format and reference of a Whiteflag message and returns the result. Typically used for validation and testing, because this is automatically done for incoming and outgoing messages. This operation may be disabled in the configuration.

Body parameter

{
  "MetaHeader": null,
  "MessageHeader": null,
  "MessageBody": null
}

Parameters

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": [
    {
      "MetaHeader": null,
      "MessageHeader": null,
      "MessageBody": null
    }
  ]
}

Responses

Response Schema

getMessageReferences

GET /messages/references

Returns an array of all Whiteflag messages referencing the message with the given transaction hash. This operation may be disabled in the configuration.

Parameters

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": [
    {
      "MetaHeader": null,
      "MessageHeader": null,
      "MessageBody": null
    }
  ]
}

Responses

Response Schema

getMessageSequence

GET /messages/sequence

Returns an array with the Whiteflag messages in a sequence starting with the message with the given transaction hash. This operation may be disabled in the configuration.

Parameters

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": [
    {
      "MetaHeader": null,
      "MessageHeader": null,
      "MessageBody": null
    }
  ]
}

Responses

Response Schema

Blockchains

Endpoints for operations related to a specific blockchain and blockchain accounts, such as blockchain information settings, account information and authentication signatures.

getAllBlockchains

GET /blockchains

Returns an array with the names of all blockchains, regardless of their current status. This operation may be disabled in the configuration.

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": [
    "string"
  ]
}

Responses

Response Schema

getBlockchainState

GET /blockchains/{blockchain}

Returns the configuration and status of the specified blockchain. This operation may be disabled in the configuration.

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

getAccounts

GET /blockchains/{blockchain}/accounts

Returns an array with all account addresses of the specified blockchain. This operation may be disabled in the configuration.

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": [
    "string"
  ]
}

Responses

Response Schema

createAccount

POST /blockchains/{blockchain}/accounts

Creates a new account for the specified blockchain. This operation may be disabled in the configuration.

Body parameter

{
  "privateKey": "string"
}

Parameters

Example responses

201 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

getAccount

GET /blockchains/{blockchain}/accounts/{account}

Returns the details of the specified blockchain account. This operation may be disabled in the configuration.

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

updateAccount

PATCH /blockchains/{blockchain}/accounts/{account}

Updates or adds custom properties of the specified blockchain account. Please BE CAREFUL as all attributes can be changed, which may result in an unusable account. This operation may be disabled in the configuration.

Body parameter

false

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

deleteAccount

DELETE /blockchains/{blockchain}/accounts/{account}

Deletes the specified blockchain account. Please BE CAREFUL as all blockchain data will be unrecoverably deleted. This operation may be disabled in the configuration.

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

createSignature

POST /blockchains/{blockchain}/accounts/{account}/sign

Signs a Whiteflag authentication payload for the blockchain address specified in the payload and returns the resulting signature to be used with authentication method 1. This signature should be made available on an internet resource to which an A1 authentication message refers. This operation may be disabled in the configuration.

Body parameter

false

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

transferFunds

POST /blockchains/{blockchain}/accounts/{account}/transfer

Transfers value to another blockchain account. This operation may be disabled in the configuration.

Body parameter

{
  "fromAddress": "string",
  "toAddress": "string",
  "value": "string"
}

Parameters

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": {
    "transactionHash": "string"
  }
}

Responses

Response Schema

Authentication

Endpoints for operations on Whiteflag authentication, such as signature and token creation and validation.

decodeSignature

POST /signature/decode

Decodes a Whiteflag authentication signature used for authentication method 1. Typically used for validation and testing, because this is automatically done for incoming messages. This operation may be disabled in the configuration.

Body parameter

false

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

verifySignature

POST /signature/verify

Verifies a Whiteflag authentication signature used for authentication method 1. Typically used for validation and testing, because this is automatically done for incoming messages. This operation may be disabled in the configuration.

Body parameter

false

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

storeAuthToken

POST /originators/tokens

Stores a unique pre-shared secret authentication token together with the provided Whiteflag originator data, used for authentication method 2. This operation may be disabled in the configuration.

Body parameter

{
  "name": "string",
  "blockchain": "string",
  "address": "string",
  "secret": "string"
}

Parameters

Example responses

202 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

getAuthToken

GET /originators/tokens/{authTokenId}

Checks for the existence of a pre-shared secret authentication token and originator data with the specified token id. This data is used for authentication method 2. This operation may be disabled in the configuration.

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

deleteAuthToken

DELETE /originators/tokens/{authTokenId}

Deletes the pre-shared secret authentication token and originator data with the specified token id. This data is used for authentication method 2. Please BE CAREFUL as the authentication token will be unrecoverably deleted. This operation may be disabled in the configuration.

Example responses

202 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

createToken

POST /token/create

Creates the non-secret Whiteflag verification token for the provided pre-shared secret authentication token used for authentication method 2. The verification token is to be used in, or to validate, the VerificationData field of an A2 authentication message. This operation may be disabled in the configuration.

Body parameter

{
  "blockchain": "string",
  "address": "string",
  "secret": "string"
}

Parameters

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": {
    "VerificationData": "string"
  }
}

Responses

Response Schema

Encryption

Endpoints for operations on Whiteflag encryption, such as managing cryptographic keys.

getPreSharedKey

GET /originators/{address}/psk/{account}

Checks for existence of a pre-shared secret encryption key for the specified Whiteflag originator to be used with the specified blockchain account. This operation may be disabled in the configuration.

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

storePreSharedKey

PUT /originators/{address}/psk/{account}

Stores or updates a pre-shared secret encryption key for the specified Whiteflag originator to be used with the specified blockchain account. This operation may be disabled in the configuration.

Body parameter

{
  "preSharedKey": "string"
}

Parameters

Example responses

202 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

deletePreSharedKey

DELETE /originators/{address}/psk/{account}

Deletes a pre-shared secret encryption key for the specified Whiteflag originator to be used with the specified blockchain account. Please BE CAREFUL as the encryption key will be unrecoverably deleted. This operation may be disabled in the configuration.

Example responses

202 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

Originators

Endpoints for operations on Whiteflag originators, such as authentication and management of shared secrets.

getAllOriginators

GET /originators

Returns the details of all known Whiteflag originators.

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

getOriginator

GET /originators/{address}

Returns the details of the specified Whiteflag originator.

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

updateOriginator

PATCH /originators/{address}

Updates the details of the specified Whiteflag originator. Only the provided properties will be updated. Please BE CAREFUL as this may result in loss of critical data such as cryptographic keys. This operation may be disabled in the configuration.

Body parameter

false

Example responses

202 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

deleteOriginator

DELETE /originators/{address}

Deletes the specified Whiteflag originator. Please BE CAREFUL as this may result in loss of critical data such as cryptographic keys. This operation may be disabled in the configuration.

Example responses

202 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

State

Endpoints for operations on the Whiteflag state of a running API instance.

getQueue

GET /queues/{queue}

Returns the requested queue in the Whiteflag state. The queues used by the API are:

• initVectors: stores the initialiation vectors received with K messages until the corresponding encrypted message is received
• blockDepths: tracks the block depth of incoming and outgoing messages until their configured confirmation depth is reached. This operation may be disabled in the configuration.

Example responses

200 Response

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "data": null
}

Responses

Response Schema

Protocol

getWFStandard

GET /protocol/whiteflag.standard.html

Returns the human readible Whiteflag protocol specification in HTML format.

Responses

getWFMessageSchema

GET /protocol/message.schema.json

Returns the Whiteflag message JSON schema.

Responses

getWFMetaheaderSchema

GET /protocol/metaheader.schema.json

Returns the Whiteflag message metaheader JSON schema.

Responses

getWFSignatureSchema

GET /protocol/signature.schema.json

Returns Whiteflag authentication signature JSON schema.

Responses

getWFStateSchema

GET /protocol/state.schema.json

Returns the Whiteflag API state JSON schema.

Responses

Icons

getIcon

GET /icons/{icon}

Returns the requested icon corresponding with a message type.

Responses

Schemas

wfMessage

{
  "MetaHeader": null,
  "MessageHeader": null,
  "MessageBody": null
}

Whiteflag Message

Properties

None

responseBodyMetaObject

{
  "additionalProperties": null,
  "operationId": "string",
  "request": {
    "client": "string",
    "method": "string",
    "endpoint": "string"
  },
  "info": [
    "string"
  ],
  "warnings": [
    "string"
  ],
  "errors": [
    "string"
  ]
}

API response metadata

Properties

responseBodyErrorObject

[
  "string"
]

API response errors

Properties

responseBodyErrors

{
  "meta": {
    "additionalProperties": null,
    "operationId": "string",
    "request": {
      "client": "string",
      "method": "string",
      "endpoint": "string"
    },
    "info": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "errors": [
    "string"
  ]
}

Properties

None