diff --git a/resources/riskline-api-access.md b/resources/riskline-api-access.md new file mode 100644 index 0000000..2dcf935 --- /dev/null +++ b/resources/riskline-api-access.md @@ -0,0 +1,70 @@ +# Riskline API Access + +*Riskline openned it's API for hackathon participants who creates a Winding +Tree OrgID. To get limited access token you need to proof that you have access +to an existing OrgID. + +Here is an example of communication which needs to be done to get limited free +access token. + +This protocol is also a proof-of-concept of programatic control of access to an +API for OrgIDs + +There is also a code snipped showing how to do sign nonce and verify it using +javascript and Metamask's web3: https://jsfiddle.net/czervenka/cye5n9m6* + + +**Riskline API base url for token acquisition:** https://api.v2-staging.riskline.com/v2/org-id +## Actors: + +- Owner of Org ID willing to get a token (further just "OrgID") +- Riskline + + +## Steps: + +### 1. Generate Nonce + +#### Request: + + POST /nonce + + +#### Response: +201 Created + { + "nonce": "a-unique-string-specific-to-this-challenge-response-series" + } + +### 2. Sign the nonce + +#### Request: +*OrgId creates message to sign as: `nonce` + `.` + `org_id_address`, signs the +message using one of OrgID's associatedKeys and sends the response.* + + POST /token + content-type: application/json; charset: utf-8 + + { + "nonce": "a-unique-string-specific-to-this-challenge-response-series", + "signature": "0x...", + "org_id_address": "0x..." + } + +#### Response: +*Riskline* + +- *checks whether the nonce was issued by Riskline,* +- *re-created the signed message (`nonce` + `.` + `org_id_address`),* +- *extracts signee from `signature` (using ethereum ecRecover function) and* +- *verifies that the extracted signee is in OrgID.associatedKeys (by calling + OrgID.hasAssociatedKey).* +*If the verification succeeds, it returns OrgID's access token.* + + + 201 Created + + { + "token": "secret-token-for-the-org-id-address", + "company_key": "key-for-the-org-id" + }