API documents

Action

The Action document is what is sent to an Action endpoint, to trigger a service or transaction. The Parameters can be inserted with data coming from an Action Descriptor or a web formed filled in by a user.

JSON Schema URL: https://developer.brickchain.com/schemas/action.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
role string The Role used for the Action
mandate string The Mandate used for the Action
nonce string The nonce used for the Action
params object Additional parameters needed to perform the Action
facts array All shared facts needed to perform the Action
contract object The message that was shown when the Action was signed

Action Descriptor

The Action Descriptor describes a specific type of Action. It is published by the Controller to the Realm, but could be broadcasted using any method. A list of Action Descriptors is shown in the App as a list of actions/services available from a Realm.

JSON Schema URL: https://developer.brickchain.com/schemas/actiondescriptor.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
binding string The binding of the descriptor, the identifier of the realm
label string The label of the action descriptor
roles array undefined
uiURI string uri Location of a web interface
uiData string Inline HTML for a web interface
nonceType string TODO
nonce undefined The nonce to use (to protect replay attacks)
nonceURI string uri Where to receive a new nonce (to protect replay attacks)
actionURI string uri The URI where to perform the Action
params object Additional parameters for the mandate, used by actions
scopes object To be able to query for additional scopes when performing the Action
icon string An icon to be used for displaying the Action Descriptor (png/jpg/svg)
keyLevel integer The key level needed to perform the action
internal boolean Do not display this descriptor in listings
contract object The message to display when signing the Action

Base

This is the Base schema for Brickchain documents. All Brickchain documents use this as its base, and includes most fields from the base document.

JSON Schema URL: https://developer.brickchain.com/schemas/base.json

property type format description
@context string uri URI to this schema document (see JSON-LD)
@type string Document type (see JSON-LD)
@subtype string Document sub type
@timestamp string date-time Timestamp of when the document was created
@id string A unique identifier of the document (uuid)
@certificateChain string The certificate chain that was used as proof of current signature
@realm string hostname The name of the realm that owns this document

Certificate Chain

This is the Certificate Chain schema… TODO.

JSON Schema URL: https://developer.brickchain.com/schemas/certificate-chain.json

property type format description
timestamp string date-time Timestamp of when the document was created
ttl integer Seconds until expiration after the document was created (timestamp)
root object The root key as JWK
subKey object The subkey as JWK
documentTypes array TODO
keyLevel integer TODO: The required key level

Contract

The Contract document is a message displayed to the user when signing a document.

JSON Schema URL: https://developer.brickchain.com/schemas/contract.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
text string A Contract message, displayed for the user for signing

Controller Binding

This is the Controller Binding schema for Brickchain documents used for binding a Realm with a Controller, see more at https://developer.brickchain.com/

JSON Schema URL: https://developer.brickchain.com/schemas/controller-binding.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
realmDescriptor object The Realm Descriptor object
adminRoles array An array of admin roles that are allow to manage the Controller
controllerCertificateChain string A Controller Certificate Chain given from the Realm
mandate string A new Mandate for the Controller issued by the Realm

Controller Descriptor

A Controller Descriptor is published by a Controller with metadata about itself.

JSON Schema URL: https://developer.brickchain.com/schemas/controller-descriptor.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
label string The label of the Controller
actionsURI string uri The URI of the Action
adminUI string The Admin UI, inline or URI
bindURI string uri The location of the binding URI, used by the Realm
key object The public JWK of the Controller
keyPurposes array An array of keypurposes
requireSetup boolean An indication that the Controller needs configuration
addBindingEndpoint string TODO
icon string An icon for the controller

Document Callback

This is the Document Callback schema… TODO.

JSON Schema URL: https://developer.brickchain.com/schemas/document-callback.json

property type format description
id string ID of the document
type string The document type
timestamp string date-time Timestamp of when the document was created
operation string TODO
linkId string TODO
linkType string TODO

Fact

A Fact is a personal identifier, something that identifies an individual or a property defining a person. An Assertion in OAuth lingo, contains a claim such as an e-mail address, Facebook ID, or passport number. The Fact is signed by an issuer - a KYC service, and stored by the user in the App. There can also be self-signed facts. Facts may be shared when requested through a Scope Request, and is bundled with other document types, for example an Action.

JSON Schema URL: https://developer.brickchain.com/schemas/fact.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
data object The fact itself, can be more than one fact of each type
iss string The issuer of the fact (in plaintext)
label string The issued id (i.e. user@example.com)
recipient string The public JWK of the receipient of the fact
ttl integer Seconds until expiration after the document was created (timestamp)

Mandate

A Mandate enables an entity (user, service) to act in a certain Role in a service connected to a Realm. A Mandate is issued to a public key, and may only be used by that key.

JSON Schema URL: https://developer.brickchain.com/schemas/mandate.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
role string The name of the mandate
label string The human readable name for the mandate (the role)
ttl integer Seconds until expiration after the document was created (timestamp)
recipient string Identifier of the receipient of the mandate
recipientName string Name of the receipient of the mandate
recipientPublicKey object The public JWK of the recipient of the fact
requestId string The id of the mandate request
sender string The id of the sender of the invite
params object Additional parameters for the mandate, used by actions

Mandate Token

This is the Mandate Token schema for Brickchain documents, see more at https://developer.brickchain.com/

JSON Schema URL: https://developer.brickchain.com/schemas/mandatetoken.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
mandate string One mandate used by the token
mandates array Can be multiple mandates
uri string uri The endpoint the client talks to (typically a web view)
ttl integer Seconds until expiration after the document was created (timestamp)

Message

This is the Mandate Token schema for Brickchain documents, see more at https://developer.brickchain.com/

JSON Schema URL: https://developer.brickchain.com/schemas/message.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
title string The message title
message string The content of the message

Multipart

This is the Multipart schema, used for embedding multiple document into one.

JSON Schema URL: https://developer.brickchain.com/schemas/multipart.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
title string The message title
parts object All parts of this multipart document

Push Message

This is the Push Message schema for Brickchain documents. Used for pushing messages to the client.

JSON Schema URL: https://developer.brickchain.com/schemas/push-message.json

property type format description
title string The message title
message string The content of the message
uri string uri TODO: An URI to a message?
data string TODO: Some data

Realm Descriptor

This is the Realm Descriptor schema for Brickchain documents, see more at https://developer.brickchain.com/

JSON Schema URL: https://developer.brickchain.com/schemas/realm-descriptor.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
name string The name of the Realm
description string The description of the Realm
publicKey object The public JWK of the Realm
endpoints array Versioned API endpoints for the Realm
inviteURL string uri The Invite URL for the Realm
servicesURL string uri Location of where to find services published by the Realm
keyHistory array A list of historical keys used by the Realm
icon undefined uri The location of the icon used for displaying the Realm
banner string uri The location of the banner used for displaying the Realm

Receipt

A Receipt is a proof of a successful transaction with a service. May be used in the App for further interaction with the service.

JSON Schema URL: https://developer.brickchain.com/schemas/receipt.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
role string The Role that executed the Action that formed the Receipt
action string The Action document that formed the Receipt
uri string The URI for doing updates on the Receipt
jwt string A JWT to be used when doing updates on the Receipt
intervals array An array of Intervals, used for events or bookings
label string The label describing the Receipt
params array TODO: perhaps remove this, all extra params used for the Action

Revocation Checksum

A signed Checksum document is published as part of a Revocation.

JSON Schema URL: https://developer.brickchain.com/schemas/revocation-checksum.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
multihash string This string contains the checksum (encoded as a multihash) of a revoked signed document.

Revocation Request

A Revocation Request is sent to a Revocation service to request a Revocation of a document signature.

JSON Schema URL: https://developer.brickchain.com/schemas/revocation-request.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
jws object This is the original signed document to be revoked.
revocationchecksum object The is the Revocation Checksum document to be published as a revocation.
priority integer This is the priority of the Revocation Request, indicating the urgency of the Revocation to be published.

Revocation

The Revocation document is published as a revocation of a signature, and the content is a JWS containing a Revocation Checksum document.

JSON Schema URL: https://developer.brickchain.com/schemas/revocation.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
checksum object This object is a Brickchain Revocation Checksum document

Scope Request

A client will use the Scope Request to fill in missing Facts for using a service.

JSON Schema URL: https://developer.brickchain.com/schemas/scope-request.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
replyTo array A list of callback addresses of where to send a response.
scopes array An array of Scope objects.
encryptTo array encryptTo specifies what recipients to encrypt the response to.
keyLevel integer TODO: The required key level
contract object The Contract, a message to display to the user.

Signature Request

This Signature Request is used to request a user to sign a document.

JSON Schema URL: https://developer.brickchain.com/schemas/signature-request.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
replyTo array A list of callback addresses of where to send a response.
document string The document requested for signing.
keyLevel integer TODO: The required key level

URL Response

This is the URL Response schema, used for sending the Integrity app an URL as a response.

JSON Schema URL: https://developer.brickchain.com/schemas/url-response.json

Based on this JSON Schema: https://developer.brickchain.com/schemas/base.json

property type format description
url string uri The URL.