Whiteflag API v1.0.1

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

Name	In	Type	Required	Description
blockchain	query	string	false	The name of a blockchain
transactionHash	query	string	false	The hash of a blockchain transaction
originatorAddress	query	string	false	The blockchain address of an originator
originatorPubKey	query	string	false	The public key of an originator
recipientAddress	query	string	false	The blockchain address of the recipient (only known for decrypted messages)
transceiveDirection	query	string	false	The transceive direction indicating if a message has been sent (TX) or has been received (RX)

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

Status	Meaning	Description	Schema
200	OK	Successfully processed Whiteflag message query and returning an array of messages	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Name	In	Type	Required	Description
body	body	wfMessage	false	Whiteflag message to be send, encoded/ecrypted, or validated

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

Status	Meaning	Description	Schema
200	OK	Successfully processed the Whiteflag message and returning the message with updated MetaHeader	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors
503	Service Unavailable	Function currently not available, such as unavailable blockchain connection	responseBodyErrors

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

Name	In	Type	Required	Description
body	body	object	false	Whiteflag message to be decoded/decrypted

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

Status	Meaning	Description	Schema
200	OK	Successfully processed the Whiteflag message and returning the message with updated MetaHeader	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors

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

Name	In	Type	Required	Description
body	body	wfMessage	false	Whiteflag message to be send, encoded/ecrypted, or validated

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

Status	Meaning	Description	Schema
200	OK	Successfully processed the Whiteflag message and returning the message with updated MetaHeader	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors

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

Name	In	Type	Required	Description
body	body	object	false	Whiteflag message to be decoded/decrypted

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

Status	Meaning	Description	Schema
200	OK	Successfully processed the Whiteflag message and returning the message with updated MetaHeader	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors

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

Name	In	Type	Required	Description
body	body	wfMessage	false	Whiteflag message to be send, encoded/ecrypted, or validated

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

Status	Meaning	Description	Schema
200	OK	Successfully processed Whiteflag message query and returning an array of messages	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Name	In	Type	Required	Description
transactionHash	query	string	true	The hash of a blockchain transaction
blockchain	query	string	false	The name of a blockchain

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

Status	Meaning	Description	Schema
200	OK	Successfully processed Whiteflag message query and returning an array of messages	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors
503	Service Unavailable	Function currently not available, such as unavailable blockchain connection	responseBodyErrors

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

Name	In	Type	Required	Description
transactionHash	query	string	true	The hash of a blockchain transaction
blockchain	query	string	false	The name of a blockchain

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

Status	Meaning	Description	Schema
200	OK	Successfully processed Whiteflag message query and returning an array of messages	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors
503	Service Unavailable	Function currently not available, such as unavailable blockchain connection	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully retrieved and returning the names of all configured blockchains	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully retrieved and returning the blockchain configuration and status	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully retrieved and returning the addresses of the blockchain accounts	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Name	In	Type	Required	Description
body	body	object	false	Blockchain account data
» privateKey	body	string	false	Optional private key in raw hexadecimal format to create account with

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

Status	Meaning	Description	Schema
201	Created	Successfully created the blockchain account, and returning account data	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
409	Conflict	The request conflicts with an already existing resource	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors
503	Service Unavailable	Function currently not available, such as unavailable blockchain connection	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully retrieved, updated or deleted the blockchain account, and returning account data	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully retrieved, updated or deleted the blockchain account, and returning account data	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors
503	Service Unavailable	Function currently not available, such as unavailable blockchain connection	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully retrieved, updated or deleted the blockchain account, and returning account data	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors
503	Service Unavailable	Function currently not available, such as unavailable blockchain connection	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully processed the Whiteflag authentication signature and returning the result	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors
503	Service Unavailable	Function currently not available, such as unavailable blockchain connection	responseBodyErrors

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

Name	In	Type	Required	Description
body	body	object	false	Data required to transfer value to another blockchain account
» fromAddress	body	string	false	The address of the blockchain account to transfer value from
» toAddress	body	string	true	The address of the blockchain account to transfer value to
» value	body	string	true	Value to be transferred in the main currency of the blockchain

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

Status	Meaning	Description	Schema
200	OK	Successfully transferred value to another blockchain account and returning the transaction hash	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors
503	Service Unavailable	Function currently not available, such as unavailable blockchain connection	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully processed the Whiteflag authentication signature and returning the result	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully processed the Whiteflag authentication signature and returning the result	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors
503	Service Unavailable	Function currently not available, such as unavailable blockchain connection	responseBodyErrors

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

Name	In	Type	Required	Description
body	body	object	false	Pre-shared secret authentication token data
» name	body	string	true	The name of the orginator
» blockchain	body	string	true	The name of the blockchain used by the originator
» address	body	string	false	The blockchain address of the originator, if already known
» secret	body	string	true	A pre-shared secret authentication token in raw hexadecimal format

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

Status	Meaning	Description	Schema
202	Accepted	Successfully accepted the new authentication token for the Whiteflag originator	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
409	Conflict	The request conflicts with an already existing resource	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	An authentication token for the Whiteflag originator is available	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
202	Accepted	Successfully accepted the delete request for the authentication token of the Whiteflag originator	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Name	In	Type	Required	Description
body	body	object	false	Whiteflag Authentication Token
» blockchain	body	string	true	The name of the blockchain used by the originator
» address	body	string	true	The address of the originator blockchain account with which the token is used
» secret	body	string	true	A pre-shared secret authentication token in raw hexadecimal format

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

Status	Meaning	Description	Schema
200	OK	Successfully created the Whiteflag authentication token verification data and returning the result	Inline
400	Bad Request	Invalid request, typically because of a malformed syntax or protocol error	responseBodyErrors
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors
501	Not Implemented	Function not implemented, such as a missing protocol feature or not implemented blockchain	responseBodyErrors
503	Service Unavailable	Function currently not available, such as unavailable blockchain connection	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	A pre-shared encryption key for the Whiteflag originator is available	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Name	In	Type	Required	Description
body	body	object	false	Pre-shared encryption key data
» preSharedKey	body	string	true	A pre-shared secret encryption key in raw hexadecimal format

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

Status	Meaning	Description	Schema
202	Accepted	Successfully accepted new or updated pre-shared encryption key for the Whiteflag originator	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
202	Accepted	Successfully accepted the delete request for the pre-shared encryption key for the Whiteflag originators	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully retrieved and returning known Whiteflag originators	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
200	OK	Successfully retrieved and returning known Whiteflag originator	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
202	Accepted	Successfully retrieved and returning known Whiteflag originators	Inline
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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

Status	Meaning	Description	Schema
202	Accepted	Successfully retrieved and returning known Whiteflag originators	Inline
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

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": {}
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully retrieved and returning the queue of the running API instance	Inline
401	Unauthorized	Authentication is required and was either not provided or has failed	responseBodyErrors
403	Forbidden	Request is not allowed, typically because the operation is disabled in the configuration	responseBodyErrors
404	Not Found	Requested resource not found or no data available	responseBodyErrors
500	Internal Server Error	Internal error preventing the running API instance to process the request	responseBodyErrors

Response Schema

Protocol