Introduction to the sTeX API

This documentation will allow you to manage your account and your documents through our API, and also serves the need of explaining more about how sTeX works in all its technical details.

Manage your account

Obtaining the Auth Token

sTeX's auth mechanism relies on the so called sauth or stellar_auth, which simply is the result of an encryption between a private user key and a temporary signature. It is called stellar auth because once the app verifies the validity of a sauth, it returns the stellar secret key of the user's account (remember sTeX is a centralised and custodial service).

To obtain this token, you'll currently have to make a request as follows:

POST /signin

{
	"email": YOUR_EMAIL,
	"password": YOUR_PASSWORD
}

We understand this isn't a best practice for an API, thus are considering the idea of allowing to create API auth tokens.

Managing your documents

Listing all documents

GET /documents

Auth: YOUR_AUTH_TOKEN

Create new document

POST /document/new

Auth: YOUR_AUTH_TOKEN

This simply creates a document entry under the user in our database. Title and contents are set through the edit document section.

This request returns the id of the document.

Edit document

Content

POST /document/edit/:document_id

Auth: YOUR_AUTH_TOKEN


{
    "target":"content",
    "content": LATEX_CODE
}

Name

POST /document/edit/:document_id

Auth: YOUR_AUTH_TOKEN


{
    "target":"name",
    "content": NAME
}

Read document

GET /document/:document_id

Auth: YOUR_AUTH_TOKEN

Delete document

POST /document/:document_id/delete

Auth: YOUR_AUTH_TOKEN

POST /document/:document_id/share

Auth: YOUR_AUTH_TOKEN

{
	"invited": EMAIL,
	"role": "editor" | "reader"
}

Document Tokenisation

Document tokenisation is very important is sTeX, but what exactly is happening as we tokenise a document we have written? This is a high-level description of how that works.

1. Auth verificaton

This is a step that takes place in all of the described API endpoints, were the backend verifies the validity of the provided auth token.

2. Building the transaction

Tokenisation happens as soon as we submit transaction to the Stellar network with the following operations:

creating the document on chain (remember that the document keypair already exists)
add the specified holder as the only signer of the document (this makes sure everything after the tokenisation is completely decentralised and non custodial)
adding the hash of the contents to the document account as data attribute. This transaction also has some sponsoring ops to make the process smoother which we are not specifiying for simplicity.

4. Tokenise: sending the transaction

This process, which is completed client-side so the user can confirm the transaction, consists of simply sending the transaction to the network.

Tokenise a document

POST /stellar/bridge/detach

Auth: YOUR_AUTH_TOKEN

{
    "id": DOCUMENT_ID,
    "holder": HOLDER_PUBLIC_KEY
}

The sTeX decentralised marketplace

A more detailed specification of the marketplace and the degree of decentralisation it offers is currently being written, but below is how the invokation for basic trading of documents through the marketplace looks like.

Make a sell offer for a document

Invoke the contract with the following body:

{
    "timebounds":{"minTime":TIME_STAMP,"maxTime":TIME_STAMP},
    "fee":FEE,
    "action":"sellOffer",
    "sellerPK": SELLER_PUBLIC_KEY,
    "price": DOCUMENT_PRICE,
    "documentPK": DOCUMENT_ID
}

Make a buy offer for a document

Invoke the contract with the following body:

{
    "timebounds":{"minTime":TIME_STAMP,"maxTime":TIME_STAMP},
    "fee":FEE,
    "action":"buyOffer",
    "buyerPK": SELLER_PUBLIC_KEY,
    "documentPK": DOCUMENT_ID
}

sTeX documentation