GuidesAPI ReferenceChangelogDiscussions
API Reference
Woleet.io
These docs are for v1.6.2. Click to read the latest docs for v1.15.1.

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 signee'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
required

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

The value must be provided as an hexadecimal lowercase string.

This property must not be provided when creating a signature anchor: it is set at creation time to the SHA256 hash of the signature property provided (so the signature is what is actually anchored in this case).

string

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

The value must be provided as an hexadecimal lowercase string.

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 signee.

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 signedIdentity or signedIssuerDomain is provided,
signature of SHA256(hashToSign + 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 signee'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 signee can be extracted from the TLS certificate.
boolean

true (or unset) if the anchor is public (ie. discoverable by its hash or signedHash).

false if it must be private (ie. not discoverable).

If this field is not set at creation time, the anchor is public by default.

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 anchor status change:

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 Woleet in the x-woleet-signature header.

For more information see the documentation.

Responses

hash property is automatically set to the SHA256 of the signature, which is what is actually anchored into the blockchain).

400

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

402

Insufficient credits.

Updated over 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 over 6 years ago