Permission Management Service HTTP APIs Part 2
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
No special authentication requirements for this API call
The API created first (admin) user. This admin user must be used to manage new users. 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:
Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)
The API creates new user inside the current Orchestrator. User must be logged on.
If success – API returns http code 201 Created.
If request body is empty – API returns http code 400 Bad request, 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 user with given userId already exists – method fails and return http code 409 Conflict.
If any other exception throws during the user creation 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 update user user's information. User must me logged on. In the request body should be only fields that user wants to modify, fields without changes must be skipped.
If success – API returns http code 200 OK.
If request body is empty – API returns http code 400 Bad request, with error description
If given userId is absent returns http code 404 Not found.
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If any other exception throws during the user update 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 list of all users. User must be logged on.
If success – API returns http code 200 OK and body with the array of user objects. User objects does not contain password (for security purpose).
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If any other 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 delete user by given userId. User must be logged on.
If success - API returns http code 410 Gone.
If user with given userId not exist – then return http code 404 Not found.
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If any other 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 performs user login with given userId and password.
If success - method returns JSESSIONID which must be used as a cookie in all session requests.
If request body is empty – API returns http code 400 Bad request, with error description
If user with given password is incorrect – method fails and return http code 401 Unauthorized.
If any other 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 preforms user logout.
If success – API returns http code 200 OK.
If user with given JSESSIONID is incorrect or key is expired – method fails and return http code 401 Unauthorized.
If any other 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 new cloud connection for current tenant (AWS/Azure). User must be logged on. In the request body all fields are mandatory.
If success – API returns http code 200 OK and object with the information about created cloud connection except secret_access_key (for security purpose).
If request body is empty – API returns http code 400 Bad request, with error description
If user with given JSESSIONID is incorrect or key is expired – method fails and return http code 401 Unauthorized.
If any other 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 updates the existing cloud connector for current tenant by given id. User must me logged on. In the request body should be only fields that user wants to modify.
If success - API returns http code 200 OK and object with the information about updated cloud connection except password fields like secret_access_key (for security purpose).
If request body is empty – API returns http code 400 Bad request, with error description.
If request URI doesn't contain id or id is string (must be number only) – return http code 400 Bad request
If cloud connection with given id doesn't exist – then return http code 404 Not found.
If user with given JSESSIONID is incorrect or key is expired – method fails and return http code 401 Unauthorized.
If any other 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)
This API deletes the existing cloud connector for current tenant by given id. User must me logged on.
If success - API returns http code 410 Gone.
If connector with given id doesn’t exist – return http code 404 Not found
If request URI doesn't contains id or id is string (must be number only) – return http code 400 Bad request
If user with given JSESSIONID is incorrect or key is expired – method fails and return http code 401 Unauthorized.
If any other 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)
This API returns cloud connector by given id. User must me logged on. API returns cloud connector object with the fields specific to selected cloud. Selected cloud depends on field type which can be aws, azure or google. Connector objects does not contain password information like secretAccessKey.
If success – API returns http code 200 OK and body with information about cloud connector by given id.
If cloud connector with given id not exist – then return http code 404 Not found.
If request URI must have id as number, otherwise, if it's string – then return http code 400 Bad request.
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If any other 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)
This API returns the list of all existing connectors of current tenant. User must me logged on. API returns list of cloud connector objects with the fields specific to selected cloud. Selected cloud depends on field type which can be aws, azure or google. Connector objects does not contain password information like secretAccessKey.
If success – API returns http code 200 OK and body with the array of connector objects. Connector objects does not contain password information like secretAccessKey.
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If any other 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)
This API test credentials and connection of given connector by accessKeyId. User must me logged on.
If success – API returns http code 200 OK and body.
If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.
If any other exception throws during the process – then return http code 500 Internal server error with the reason description of error.
Request:
Response:
METHOD
URI
DESCRIPTION
POST
/api/v1/init/admin
Create admin
POST
/api/v1/users
Create new user
PUT
/api/v1/users/:userId
Update existing user
GET
/api/v1/users
Get users list of the tenant
DELETE
/api/v1/users/:userId
Delete user
POST
/api/v1/login
User login
GET
/api/v1/logout
User logout
POST
/api/v1/connectors
Create new connector (AWS, Azure, Google)
PUT
/api/v1/connectors/:id
Edit existing connector
GET
/api/v1/connectors
Get list of all connectors
GET
/api/v1/connectors
Get list of all connectors
DELETE
/api/v1/connectors/:id
Delete existing connector
GET
/api/v1/connectors/:id/status
Test orchestrator ↔ AWS connection
METHOD
REQUEST
BODY/HEADERS
POST
/api/v1/init/admin
HTTP CODE
BODY
MEANING
200 OK
Success!
403 Forbidden
{
"error": "Admin user 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.
METHOD
REQUEST
BODY/HEADERS
POST
/api/v1/users
HTTP CODE
BODY
MEANING
201 Created
Success!
409 Conflict
{
"error": "User already exists"
}
Error! Given userId already exists.
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
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
PUT
/api/v1/users/:userId
{
"userId": "new_mail@mail.com"
"password":"u34ff9u4n4n39u31f4"
}
Cookie: JSESSIONID=298zf09hf012fh2;
HTTP CODE
BODY
MEANING
200 OK
Success!
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": "Can't find user with id"
}
Error! Given userId doesn't exists.
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/users
Cookie: JSESSIONID=298zf09hf012fh2;
HTTP CODE
BODY
MEANING
200 OK
[
{
"userId": "first@mail.com"
// no password in response!
},
{
"userId": "second@mail.com"
// no password in response!
},
...
]
Success!
userId – unique user's identifier, in our case email.
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
DELETE
/api/v1/users/:userId
Cookie: JSESSIONID=298zf09hf012fh2;
HTTP CODE
BODY
MEANING
410 Gone
Success!
404 Not found
{
"error": "Can't find user with id"
}
Error! The user with given userId not found
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
POST
/api/v1/login
HTTP CODE
BODY
MEANING
200 OK
Set-Cookie: JSESSIONID=298zf09hf012fh2;
Success!
JSESSIONID – session key to perform the API calls from CLI/webApp
400 Bad request
{
"error": "Body can't be empty"
}
Error! Client provide incorrect request.
error – text message, describes the error reason
401 Unauthorized
{
"error": "Session expired or incorrect credentials"
}
Error! The userId, password combination is incorrect.
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/logout
Cookie: JSESSIONID=298zf09hf012fh2;
HTTP CODE
BODY
MEANING
200 OK
Success!
401 Unauthorized
{
"error": "Session expired or incorrect credentials"
}
Error! The JSESSIONID is incorrect or expired
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/connectors
{
"name": "My AWS Cloud",
"type": "aws",
// specific fields for given cloud type
}
Cookie: JSESSIONID=298zf09hf012fh2;
HTTP CODE
BODY
MEANING
201 Created
{
"id": 12,
"name": "My AWS Cloud",
"type": "aws",
// specific fields for given cloud type
}
Success!
id – unique cloud connector identifier
name – connector's alias
type – the cloud type (aws, azure, google)
Depending on type – object can contain different additional fields specific to selected cloud.
400 Bad request
{
"error": "Body can't be empty"
}
Error! Client provide incorrect request.
error – text message, describes the error reason
401 Unauthorized
{
"error": "Session expired or incorrect credentials"
}
Error! The JSESSIONID is 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
PUT
/api/v1/connectors/:id
{
"name": "New name",
"type": "aws",
// specific fields for given cloud type
}
Cookie: JSESSIONID=298zf09hf012fh2;
HTTP CODE
BODY
MEANING
200 OK
{
"id": 12,
"name": "New name",
"type": "aws",
// specific fields for given cloud type
}
Success!
id – unique cloud connector identifier
name – connector's alias
type – the cloud type (aws, azure, google)
Depending on type – object can contain different additional fields specific to selected cloud.
400 Bad request
{
"error": "Body can't be empty"
}
{
"error": "Missed or incorrect id...
}
Error! Client provide incorrect request.
error – text message, describes the error reason
404 Not found
{
"error": "Can't find Cloud Connector with id"
}
Error! The cloud connection with given id doesn't exist.
error – text message, describes the error reason
401 Unauthorized
{
"error": "Session expired or incorrect credentials"
}
Error! The JSESSIONID is incorrect or expired
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/connectors/:id
Cookie: JSESSIONID=298zf09hf012fh2;
HTTP CODE
BODY
MEANING
410 Gone
Success!
404 Not found
{
"error": "Can't find Cloud Connector with id"
}
Error! The cloud connection with given id not found in current tenant.
error – text message, describes the error reason
400 Bad request
{
"error": "Missed or incorrect id...
}
Error! Wrong id given. It must be the number only and it's mandatory.
error – text message, describes the error reason
401 Unauthorized
{
"error": "Session expired or incorrect credentials"
}
Error! The JSESSIONID is 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/connectors
Cookie: JSESSIONID=298zf09hf012fh2;
HTTP CODE
BODY
MEANING
200 OK
{
"id": 12,
"name": "My AWS Cloud",
"type": "aws",
// specific fields for given cloud type
}
Success!
id – unique cloud connector identifier
name – connector's alias
type – the cloud type (aws, azure, google)
Depending on type – object can contains different additional fields specific to selected cloud.
404 Not found
{
"error": "Can't find Cloud Connector with id"
}
Error! The cloud connection with given id not found.
error – text message, describes the error reason
400 Bad request
{
"error": "Incorrect id. Must be number only!";
}
Error! Wrong id given. It must be the number only.
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/connectors
Cookie: JSESSIONID=298zf09hf012fh2;
HTTP CODE
BODY
MEANING
200 OK
[
{
"id": 12,
"name": "My AWS Cloud",
"type": "aws",
// specific fields for AWS cloud type
},
{
"id": 18,
"name": "Microsoft Cloud",
"type": "azure",
// specific fields for AZURE cloud type
},
{
"id": 19,
"name": "My Test Google cloud",
"type": "google",
// specific fields for Google cloud type
}
...
]
Success!
id – unique cloud connector identifier
name – connector's alias
type – the cloud type (aws, azure, google)
Depending on type – object can contains different additional fields specific to selected cloud.
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/connectors/:access_key_id/status
Cookie: JSESSIONID=298zf09hf012fh2;
HTTP CODE
BODY
MEANING
200 OK
Success!
503 Service Unavailable
Error! Can't connect to AWS.
403 Forbidden
Error! Incorrect credentials. Successfully connected to AWS but rejected in credentials verification.
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.
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 2
Document ID
uid-sys-arch
Version
1.0
Status
Release
