Permission Management Service HTTP APIs Part 2

System Architecture Appendix Permission Management Service HTTP APIs
Part 2

Document ID	uid-sys-arch
Version	1.0
Status	Release

Appendix

API Documentation

The appendix contains reference information about UniquID’s API.

Permission Management Service HTTP APIs

API Overview

The described API operated with structures that always in JSON format.

All responses have Content-Type: application/json

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

Detailed API description

Create admin

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:

METHOD	REQUEST	BODY/HEADERS
POST	/api/v1/init/admin	{ "userId": "[e-mail]" "password": "14f9un34nu34f9u34" }

Response:

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.

Create new user

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:

METHOD	REQUEST	BODY/HEADERS
POST	/api/v1/users	{ "userId": "[e-mail]" "password": "14f9un34nu34f9u34" } Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	BODY	MEANING
201 Created	{ "userId": "[e-mail]" // no password in response! }	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.

Update user

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:

METHOD	REQUEST	BODY/HEADERS
PUT	/api/v1/users/:userId	{ "userId": "[e-mail]" "password":"u34ff9u4n4n39u31f4" } Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	BODY	MEANING
200 OK	{ "userId": "[e-mail]" // no password in response! }	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.

View users list

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:

METHOD	REQUEST	BODY/HEADERS
GET	/api/v1/users	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	BODY	MEANING
200 OK	[ { "userId": "[e-mail]" // no password in response! }, { "userId": "[e-mail]" // 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.

Delete user

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:

METHOD	REQUEST	BODY/HEADERS
DELETE	/api/v1/users/:userId	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

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.

Login

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:

METHOD	REQUEST	BODY/HEADERS
POST	/api/v1/login	{ "userId": "[e-mail]", "password": "14f9un34nu34f9u34" }

Response:

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.

Logout

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:

METHOD	REQUEST	BODY/HEADERS
GET	/api/v1/logout	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

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.

Create cloud connection

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:

METHOD	REQUEST	BODY/HEADERS
POST	/api/v1/connectors	{ "name": "My AWS Cloud", "type": "aws", // specific fields for given cloud type } Cookie: JSESSIONID=298zf09hf012fh2;

Response:

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.

Update cloud connection

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:

METHOD	REQUEST	BODY/HEADERS
PUT	/api/v1/connectors/:id	{ "name": "New name", "type": "aws", // specific fields for given cloud type } Cookie: JSESSIONID=298zf09hf012fh2;

Response:

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.

Delete cloud connector

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:

METHOD	REQUEST	BODY/HEADERS
DELETE	/api/v1/connectors/:id	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

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.

View connector

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:

METHOD	REQUEST	BODY/HEADERS
GET	/api/v1/connectors	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

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.

View all connectors

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:

METHOD	REQUEST	BODY/HEADERS
GET	/api/v1/connectors	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

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.

Connector status

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:

METHOD	REQUEST	BODY/HEADERS
GET	/api/v1/connectors/:access_key_id/status	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

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.