Permission Management Service HTTP APIs Part1
Last updated
Last updated
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
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:
Response:
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:
Response:
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:
Response:
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:
Response:
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:
Response:
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:
Response:
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:
Response:
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:
Response:
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:
Response:
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
METHOD
REQUEST
BODY/HEADERS
GET
/api/v1/devices
Cookie: JSESSIONID=298zf09hf012fh2;
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.
METHOD
REQUEST
BODY/HEADERS
GET
/api/v1/devices/:xpub
Cookie: JSESSIONID=298zf09hf012fh2;
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.
METHOD
REQUEST
BODY/HEADERS
GET
/api/v1/contracts
Cookie: JSESSIONID=298zf09hf012fh2;
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.
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;
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.
METHOD
REQUEST
BODY/HEADERS
DELETE
/api/v1/contracts/:txid
Cookie: JSESSIONID=298zf09hf012fh2;
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.
METHOD
REQUEST
BODY/HEADERS
GET
/api/v1/info
Cookie: JSESSIONID=298zf09hf012fh2;
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.
METHOD
REQUEST
BODY/HEADERS
GET
/api/v1/properties
Cookie: JSESSIONID=298zf09hf012fh2;
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.
METHOD
REQUEST
BODY/HEADERS
POST
/api/v1/properties
File to upload
Cookie: JSESSIONID=298zf09hf012fh2;
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.
METHOD
REQUEST
BODY/HEADERS
POST
/api/v1/init
{
"orgId": "pepsico"
}
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.
System Architecture
Appendix
Permission Management Service HTTP APIs
Part 1
Document ID
uid-sys-arch
Version
1.0
Status
Release