From 982c7acfdc0b373eed8ccf3ed40501fbbf7f6c79 Mon Sep 17 00:00:00 2001
From: Max Kalashnikoff <geekmaks@gmail.com>
Date: Tue, 9 Jul 2024 12:10:56 +0200
Subject: [PATCH] fix: adding fields description and error codes

---
 .../blockchain/blockchain-permissions-api.md  | 23 ++++++++++++-------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs/specs/servers/blockchain/blockchain-permissions-api.md b/docs/specs/servers/blockchain/blockchain-permissions-api.md
index f23ad9ee..2d9e1a10 100644
--- a/docs/specs/servers/blockchain/blockchain-permissions-api.md
+++ b/docs/specs/servers/blockchain/blockchain-permissions-api.md
@@ -1,5 +1,7 @@
 # Blockchain API Sessions and Permissions
 
+This API is **unstable**, not yet production ready and can be changed at any time.
+
 ## Sessions permissions storage
 
 ### Get permissions list for account
@@ -77,15 +79,18 @@ The POST request body should be in JSON format and following schema:
 
 #### Success response body:
 
-Response will contain a new generated ECDSA key and PCI of the new permission.
+Response will contain a new generated key and PCI of the new permission.
 
 ```typescript
 {
-    key: string,
-    pci: string
+    pci: string,
+    key: string
 }
 ```
 
+* `pci` - New unique permission controller identifier.
+* `key` - Generated signing (private) ECDSA P256 key in DER, SEC1 format encoded by Base64.
+
 #### Response error codes:
 
 * `400 Bad request` - Wrong format in request.
@@ -110,7 +115,7 @@ The POST request body should be in JSON format and following schema:
     context: {
       {
         signer: {
-          type: string,
+          permissionType: string,
           ids: [string]
         },
         expiry: number,
@@ -126,16 +131,17 @@ The POST request body should be in JSON format and following schema:
 ```
 
 * `pci` - PCI to revoke.
-* `signature` - Signature signed by the key provided during the permission creation.
+* `signature` - Signature of canonicalized JSON `context` object signed by the key provided during the permission creation. The signature must be provided as DER, SEC1 and encoded in Base64 format.
 * `context` - Permissions context object to update.
 
 #### Success response body:
 
-* `202 Accepted` - Successfully updated.
+* `200 Ok` - Successfully updated.
 
 #### Response error codes:
 
 * `400 Bad request` - Wrong format in request.
+* `401 Unauthorized` - Wrong signature.
 
 ## Revoke permission 
 
@@ -158,12 +164,13 @@ The POST request body should be in JSON format and following schema:
 ```
 
 * `pci` - PCI to revoke.
-* `signature` - Signature signed by the key provided during the permission creation.
+* `signature` - Signature of signed `pci` field by the key provided during the permission creation. The signature must be provided as DER, SEC1 and encoded in Base64 format.
 
 #### Success response body:
 
-* `202 Accepted` - Successfully revoked.
+* `200 Ok` - Successfully revoked.
 
 #### Response error codes:
 
 * `400 Bad request` - Wrong format in request.
+* `401 Unauthorized` - Wrong signature.