Permission Management Service HTTP APIs Part1
PreviousIdentity Self-Provisioning Service HTTP APINextPermission Management Service HTTP APIs Part 2
Last updated
Last updated
System Architecture Appendix Permission Management Service HTTP APIs |
Part 1 |
Document ID | uid-sys-arch |
Version | 1.0 |
Status | Release |
The appendix contains reference information about UniquID’s API.
The described API operated with structures that always in JSON format.
All responses have Content-Type: application/json
METHOD | URI | DESCRIPTION |
GET | /api/v1/devices | Get all managed devices |
GET | /api/v1/devices/:xpub | Get info about specific device |
GET | /api/v1/contracts | Get list of the access contracts |
POST | /api/v1/contracts | Create new access contracts |
DELETE | /api/v1/contracts/:txid | Revoke existing access contracts |
GET | /api/v1/info | Returns information about orchestrator |
GET | /api/v1/properties | Get orchestrator properties |
POST | /api/v1/properties | Upload data and saves the file on disk |
POST | /api/v1/init | Init orchestrator |
Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)
The API returns all managed devices. User must be logged on.
If success - API returns a JSON array of all the orchestrated devices in the response body.
If no device found – then returns http code 404 Not found, with error description in the body.
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.
Request:
METHOD | REQUEST | BODY/HEADERS |
GET | /api/v1/devices | Cookie: JSESSIONID=298zf09hf012fh2; |
Response:
HTTP CODE | BODY | MEANING |
200 OK | [ { "name": "device_name_1", "xpub": "public_key_1", "recipe": "test", "contracts": 1, "shared": false }, { "name": "device_name_2", "xpub": "public_key_2", "recipe": "test", "contracts": 1, "shared": false }, ... ] | Success! name – name of the device xpub – public key of the device recipe – is always "test" contracts – number of contracts involving this device, are always 1 shared – flag indicates if this is Shared Device; provided for future evolution. Always false in this version |
404 Not Found | { "error": "No devices found" } | Error! Orchestrator have no devices error – text message, describes the error reason |
401 Unauthorized | { "error": "Session expired or incorrect credentials" } | Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason |
500 Internal Server Error | { stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] } | Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error. |
Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)
The API returns information about the specific device.. To use this API – User must be logged on.
If success – API returns a JSON array containing just one item in the response body.
If there is no device with given xpub – then return http code 404 Not found with error description
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.
Request:
METHOD | REQUEST | BODY/HEADERS |
GET | /api/v1/devices/:xpub | Cookie: JSESSIONID=298zf09hf012fh2; |
Response:
HTTP CODE | BODY | MEANING |
200 OK | { "name":" dev_name_1", "xpub": "pub_key_1", "recipe": "test", "contracts": 1, "shared": false } | Success! name – name of the device xpub – public key of the device recipe - is always "test" contracts – number of contracts involving this device. Is always 1 shared – flag indicates if this is Shared Device; provided for future evolution. Always false in this version |
404 Not found | { "error": "Device with xpub: 'af3J42if4828c2' not found" } | Error! Orchestrator have no device with given xpub error – text message, describes the error reason |
401 Unauthorized | { "error": "Session expired or incorrect credentials" } | Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason |
500 Internal Server Error | { stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] } | Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error. |
Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)
The API returns a list of all the Access Contracts of current tenant. To use this API – User must be logged on.
If success – API returns a JSON array containing all the access contracts in the response body.
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.
Request:
METHOD | REQUEST | BODY/HEADERS |
GET | /api/v1/contracts | Cookie: JSESSIONID=298zf09hf012fh2; |
Response:
HTTP CODE | BODY | MEANING |
200 OK | [ { "provider": { "name":"device_name_1", "xpub":"device_xpub", "address":"device_address_1" }, "user": { "name":"device_name_2", "xpub":"device_xpub_2", "address":"device_address_2" }, "revoker": { "name":"device_name_3", "xpub":"device_xpub_3", "address":"device_address_3" }, "txid":"txid", "recipe":"Access", "status":"ACTIVE", "timestamp":123456789, "functions": [34,35], "shared": false }, … ] | Success! provider – provider device information user – user device information revoker – revoker device information txid – unique identifier of the transaction recipe – is always "Access" status – status of the contract. It can be 'pending', 'active' or 'revoked' timestamp – creation time of the contract functions – functionality enabled by the "provider" to the "user" shared – flag indicates if this is Shared Contract; provided for future evolution. Always false in this version |
401 Unauthorized | { "error": "Session expired or incorrect credentials" } | Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason |
500 Internal Server Error | { stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] } | Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error. |
Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)
The API creates a new Access Contract between devices provider and user. This API allows to create contract and if both devices belongs to current tenant. To use this API - User must be logged on.
If success – API returns http code 200 OK
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If request body is empty – API returns http code 400 Bad request, with error description.
If provider does not exist in orchestrator database – API returns http code 404 Provider with given Xpub not found.
If user does not exist in orchestrator database – API returns http code 404 User with given Xpub not found.
If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.
Request:
METHOD | REQUEST | BODY/HEADERS |
POST | /api/v1/contracts | { "provider":"device_xpub", "user":"device_xpub", "functions": [34,35] } "functions" is optional. If not set, then the orchestrator will allow functions 33 to 37. Cookie: JSESSIONID=298zf09hf012fh2; |
Response:
HTTP CODE | BODY | MEANING |
200 OK | Success! | |
401 Unauthorized | { "error": "Session expired or incorrect credentials" } | Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason |
400 Bad request | { "error": "Body can't be empty" } | Error! Client provide incorrect request. error – text message, describes the error reason |
404 Not found | { "error": "Provider with given Xpub not found" } | Error! There is no provider with given Xpub in database of Orchestrator error – text message, describes the error reason |
{ "error": "User with given Xpub not found" } | Error! There is no user with given Xpub in database of Orchestrator error – text message, describes the error reason | |
500 Internal Server Error | { stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] } | Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error. |
Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)
The API deletes existing Access Contract. To use this API – User must be logged on.
If success – API returns http code 200 OK
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If contract with given txid not exist – then return http code 404 Not found
If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.
Request:
METHOD | REQUEST | BODY/HEADERS |
DELETE | /api/v1/contracts/:txid | Cookie: JSESSIONID=298zf09hf012fh2; |
Response:
HTTP CODE | BODY | MEANING |
200 OK | Success! | |
401 Unauthorized | { "error": "Session expired or incorrect credentials" } | Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason |
404 Not found | { "error": "Contract not found" } | Error! Resource not found. error – text message, describes the error reason |
500 Internal Server Error | { stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] } | Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error. |
Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)
The API returns the information about the current Orchestrator. User must be logged on.
If success – API returns the information about the current Orchestrator in the content body and http code 200 OK
If the request has extra path – method returns http code 400 Bad request with "path not implemented" in the content body.
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.
Request:
METHOD | REQUEST | BODY/HEADERS |
GET | /api/v1/info | Cookie: JSESSIONID=298zf09hf012fh2; |
Response:
HTTP CODE | BODY | MEANING |
200 OK | { "name":"OrchestratorNJI95H28R4TA", "publicKey": "tpubDBYT1CEYNPzH9AveZd55....", "providerBalance":0, "userBalance":0, "topupAddress":"mkZusM4szmV7pkWYDvdVTHk28Jm..." } | Success! name – name of the Orchestrator publicKey – Orchestrator’s public key providerBalance – coin balance of the "provider" bip32 hierarchy userBalance – coin balance of the "user" bip32 hierarchy topupAddress – address to use to recharge the Orchestrator |
400 bad request | Path not implemented | Error! Extra path information not permitted |
401 Unauthorized | { "error": "Session expired or incorrect credentials" } | Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason |
500 Internal Server Error | { stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] } | Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error. |
Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)
The API allows to list the properties of the current Orchestrator. User must be logged on.
If success – API returns the properties of the current Orchestrator in the content body and http code 200 OK
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.
Request:
METHOD | REQUEST | BODY/HEADERS |
GET | /api/v1/properties | Cookie: JSESSIONID=298zf09hf012fh2; |
Response:
HTTP CODE | REQUEST | MEANING |
200 OK | { "network":"", "mqttTopic":"", "mqttBroker":"", "httpPort":"", "insightApiUrl":"", "registryUrl":"", "imprinterUrl":"" } | Success! network – blockchain network mqttTopic – listening topic mqttBroker – broker for MQTT communication insightApiUrl – blockchain API service registryUrl – URL of the registry service imprinterUrl – URL of the imprinter service |
401 Unauthorized | { "error": "Session expired or incorrect credentials" } | Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason |
500 Internal Server Error | { stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] } | Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error. |
Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)
The API allows to upload a settings file to the current Orchestrator. User must be logged on.
If success – API returns the information about the current Orchestrator in the content body and http code 200 OK
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If request body is empty – API returns http code 400 Bad request, with error description
If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.
Request:
METHOD | REQUEST | BODY/HEADERS |
POST | /api/v1/properties | File to upload Cookie: JSESSIONID=298zf09hf012fh2; |
Response:
HTTP CODE | BODY | MEANING |
200 OK | Success! | |
401 Unauthorized | { "error": "Session expired or incorrect credentials" } | Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason |
400 Bad request | { "error": "Body can't be empty" } | Error! Client provide incorrect request. error – text message, describes the error reason |
500 Internal Server Error | { stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] } | Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error. |
No special authentication requirements for this API call
The API initialize orchestrator (set organization). This organization needs to start working orchestrator and use to communicate between another components of the system. The Init method can be called only once at the beginning. All other APIs couldn't be called before the Init call.
If success – API returns https code 200 OK.
If request body is empty – API returns http code 400 Bad request, with error description
If any other exception throws during the init orchestrator process – then return http code 500 Internal server error with the reason description of error.
Request:
METHOD | REQUEST | BODY/HEADERS |
POST | /api/v1/init | { "orgId": "pepsico" } |
Response:
HTTP CODE | BODY | MEANING |
200 OK | Success! | |
403 Forbidden | { "error": "Settings already initialized" } | Error! The Orchestrator already initialized. The second call of Init not allowed. error – text message, describes the error reason |
400 Bad request | { "error": "Body can't be empty" } | Error! Client provide incorrect request. error – text message, describes the error reason |
500 Internal Server Error | { stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] } | Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error. |
