GuidesAPI ReferenceChangelogDiscussions
API Reference
Woleet.io

Create a new anchor.

post
https://api.woleet.io/v1/anchor

Use this operation to create a new anchor of one of these two types:

  • a data anchor (generating a proof of existence receipt) allows to prove the existence of some data at some point in time.
  • a signature anchor (generating a proof of signature receipt) allows to prove the existence of the signature of some data at some point in time, the validity of the signature and the signer's identity.

The properties id, created, lastModified, status, timestamp and confirmations are read-only and so must not be provided: they are managed by the platform and added to the returned anchor.

For data anchors, only the properties name and hash are required: the hash property must be the SHA256 hash of the data to anchor, and must be computed caller side. This allows not to leak the original data.

For signature anchors, only the properties name, signedHash, signature and pubKey are required (though the identityURL property is highly recommended): the signedHash property must be the SHA256 hash of the data to sign. This allows not to leak the original data and to keep the actual signed data small (signing the digest is equivalent to signing the original data).

Be sure to have at least 1 anchoring credit on your account. The signature property must contain a valid signature of the data property using the private key paired with the pubKey public key.

Body Params

Anchor object to create.

string
required

Name of the anchor (doesn't need to be unique).

string

SHA256 hash (ie. the fingerprint) of the data to anchor.

The value must be provided as an hexadecimal lowercase string. The hash of the empty file is forbidden.

This property must not be provided when creating a signature anchor: it is automatically set at creation time to the SHA256 hash of the signature property provided, meaning that the signature is the actual anchored data.

string

SHA256 hash (ie. the fingerprint) of the signed data.

The value must be provided as an hexadecimal lowercase string. The hash of the empty file is forbidden.

This property must not be provided when creating a data anchor.

string

X500 Distinguished Name representing the signed identity.

This property must not be provided when creating a data anchor.

string

Domain name of the identity issuer (ie. of the organization who verified the identity).

If set, the domain name of the identity URL must be included in the signedIssuerDomain domain name.

This property must not be provided when creating a data anchor.

string

Public key of the signer.

Currently only Bitcoin addresses are supported.

This property must not be provided when creating a data anchor.

string

Signature of the signedHash property using the public key pubKey, or, if any of the signedIdentity or signedIssuerDomain properties are provided,
signature of SHA256(signedHash + signedIdentity + signedIssuerDomain) using the public key pubKey.

Only Bitcoin signatures are currently supported.

This property must not be provided when creating a data anchor.

string

Web hook of the identity server to use to verify the signer's identity.

This URL allows to retrieve the identity associated to the public key pubKey.
It can also be used to verify that the identity server (itself identified by the TLS certificate of the URL) controls the key used to sign (ie. owns the private part of the key pair) by requesting it to sign some random data.

This URL MUST use an HTTPS scheme with a valid and non expired TLS certificate.

This URL MUST implement the following GET operation:

Query parameters:

  • pubKey: the public key to be verified - mandatory
  • leftData: the left part of the data to be signed (generated randomly by the caller) - if set, the identity server MAY provide a signature

    Output:

    A JSON object with:
  • rightData: the right part of the data signed (generated randomly by the identity server) - optional
  • signature: the signature of the string leftData + rightData using the public key pubKey - optional
  • identity: the X500 identity associated to the key claimed by the identity server - optional
  • key: additional information about the key - optional

    If identity is not provided, signature and rightData MUST be provided: in such a case the identity of the signer can be extracted from the TLS certificate.
boolean

true (or unset) if the anchor is public (ie. discoverable by its hash or signedHash) or false if it must be private (ie. not discoverable).

boolean

true if the proof receipt must be sent by email once available, or false (or unset) if not.

tags
array of strings

Set of tags associated to the anchor. There is no restriction on tag names, except they cannot contain spaces.

Tags are aimed at classifying and searching anchors.

tags
string

Web hook to be called by the platform whenever the status property of the anchor changes:

the platform does a POST request on this URL with the anchor as a JSON object in the request body.

Verifying the authenticity of the callback can be done by checking the HMAC-SHA1 signature of the request body provided by the platform in the x-woleet-signature header.

Please refer to the documentation for more details.

Responses

400

Invalid request. More details are returned in the response body as a JSON object.

402

Insufficient credits.

Updated almost 6 years ago

Language
Credentials
:
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated almost 6 years ago