Documentation

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://schema.brickchain.com/v2/action.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
mandates array<string> A list of Mandates used for the Action.
nonce string The nonce used for the Action to prevent replay attacks.
params object Additional parameters needed to perform the Action. It is up to the receiving controller to determine the use of the parameters.
facts array<string> All shared facts needed to perform the Action.
contract string The signed Contract (compact encoded JWS) 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://schema.brickchain.com/v2/actiondescriptor.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
label string The label describing the Action Descriptor.
roles array<string> A list of roles that can use the action, can be used to lookup mandates for action.
uiURI string uri Location of a web interface. Inline HTML data can be provided using a data URI.
actionURI string uri The URI where to perform the Action.
refreshURI string uri A URI where an updated version of this Action Descriptor can be retrieved. Used for dynamic Action Descriptor content, to include device state.
params object Additional parameters describing any necessary details of the service, used by Actions.
scopes array<scope> A list of scope objects, asking the user to share facts with the service controller when performing an Action.
icon string uri An icon to be used for displaying the Action Descriptor (png/jpg/svg).
keyLevel integer The minimum key level needed to perform the action.
internal boolean An moption to not display this descriptor in listings.
contract undefined 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 all fields from the base document.

JSON Schema URL: https://schema.brickchain.com/v2/base.json

property type description
@type string uri Document type as URI, subtype after ‘#’.
@timestamp string date-time Timestamp of when the document was created.
@id string A unique identifier of the document (uuid).
@certificate string The certificate chain that was used as proof of current signature.
@realm string hostname The name of the realm that issued this document.

Certificate

This is the certificate schema that contains any signature from an issuer certifying that the current key is allowed to sign certain documents types. The base document can include the certificate as a proof.

JSON Schema URL: https://schema.brickchain.com/v2/certificate.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
ttl integer Seconds until expiration after the document was created (timestamp).
issuer object The issuer key as JWK
subject object The subject key as JWK
documentTypes array<string> A list of document types that the subject can sign.
allowedRoles array<string> A list of roles that the subject can assume.
keyLevel integer The minimum required key level for subsequent certificates in the certificate chain.

Contract

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

JSON Schema URL: https://schema.brickchain.com/v2/contract.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
text string A Contract message, displayed for the user for signing.
attachments array<object>
undefined

Controller Binding

This is the Controller Binding schema for Brickchain documents used for binding a Realm with a Controller.

JSON Schema URL: https://schema.brickchain.com/v2/controller-binding.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
realmDescriptor object The Realm Descriptor object.
adminRoles array<string> An array of admin roles that are allow to manage the Controller.
controllerCertificate string A Controller Certificate given from the Realm.
mandates array<string> A list of Mandates that allows the controller to act as a certain role in the realm.

Controller Descriptor

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

JSON Schema URL: https://schema.brickchain.com/v2/controller-descriptor.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
label string The label of the Controller.
actionsURI string uri Used to retrieve Action Descriptors from controller.
adminUI string The Admin UI, inline or URI.
bindURI string uri The location of the binding URI, used by the Realm.
key object The controller’s public key as JWK.
keyPurposes array<keypurpose> An array of keypurposes, describes document types for the controller’s certificate.
requireSetup boolean An indication that the Controller needs configuration.
addBindingEndpoint string Can be used to create new empty bindings on the controller.
icon string An icon for the controller.

Fact Signature

A Fact Signature document is an attachment to a Fact that allows a Fact to have multiple signatures.

JSON Schema URL: https://schema.brickchain.com/v2/fact-signature.json

property type description
certificate string The certificate from the issuing realm.
timestamp string date-time The date and time of the issued fact signature.
expires string date-time The date and time of when this fact signature expires.
subject object The subject the signature is issued for as a JWK
hash string The checksum of the fact that this fact signature covers.
metadata object Additional data that a KYC provider can set. Should not contain sensitive information.

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://schema.brickchain.com/v2/fact.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
data object The fact itself, can be more than one fact of each type.
label string The human readable label of the fact.
signatures array<fact-signature> An array of Fact Signatures.

Key Purpose

The Key Purpose documents is a part of the Controller Descriptor schema, and desribes to the Realm what kind of Document Types is needed in the Certificate.

JSON Schema URL: https://schema.brickchain.com/v2/keypurpose.json

property type description
documentType string The document type needed in the certificate.
required boolean This document type may be optional or required.
description string The description of (the requirement of) the document type.

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://schema.brickchain.com/v2/mandate.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
role string The name of the mandate.
roleName string The human readable name for the mandate (the role).
validFrom string date-time The date and time the Mandate is valid from.
validUntil string date-time The date and time the Mandate is valid until.
recipient object The public JWK of the receipent of the Mandate.
sender string The key id of the sender of the invite.
params object Additional parameters for the mandate, used by actions.

Mandate Token

The Mandate Token is an encapsulated object containing Mandates. Used for inclusion in HTTP headers, when interacting with web views.

JSON Schema URL: https://schema.brickchain.com/v2/mandatetoken.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
mandates array<string> Can be multiple mandates encoded as compact JWS
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

The Message document is used to display a message in the app. Mostly used in multipart-messages, as part of a larger payload.

JSON Schema URL: https://schema.brickchain.com/v2/message.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type 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://schema.brickchain.com/v2/multipart.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
parts array<object>
All parts of this multipart document.

Realm Descriptor

This is the Realm Descriptor schema, includes all public metadata about a realm.

JSON Schema URL: https://schema.brickchain.com/v2/realm-descriptor.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
label string The label of the Realm.
publicKey object The public JWK of the Realm.
inviteURL string uri The Invite URL for the Realm.
servicesURL string uri Location of where to find services published by the Realm.
icon string 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://schema.brickchain.com/v2/receipt.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
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<object>
An array of Intervals, used for events or bookings.
label string The label describing the Receipt.

Revocation Checksum

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

JSON Schema URL: https://schema.brickchain.com/v2/revocation-checksum.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type 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://schema.brickchain.com/v2/revocation-request.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type 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://schema.brickchain.com/v2/revocation.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type 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://schema.brickchain.com/v2/scope-request.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
replyTo array<string> A list of callback addresses of where to send a response.
scopes array<scope> An array of Scope objects.
keyLevel integer The minimum required key level that signs the response.
contract contract The Contract, a message to display to the user.

Scope

A Scope is used as part of a Scope Request or an Action Descriptor. Contains the type of scope, and a link of where to get it. It does not include the Base document, and is not signed as a standalone object.

JSON Schema URL: https://schema.brickchain.com/v2/scope.json

property type description
name string The name of the Scope.
link string uri An URI of where to retrieve a fact of this type of fact.
required boolean This fact may be optional or required.

Signature Request

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

JSON Schema URL: https://schema.brickchain.com/v2/signature-request.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
replyTo array<string> A list of callback addresses of where to send a response.
contract contract The contract requested for signing.
keyLevel integer The minimum 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://schema.brickchain.com/v2/url-response.json

Based on this JSON Schema: https://schema.brickchain.com/v2/base.json

property type description
url string uri The URL.