diff --git a/Api.md b/Api.md index 6c97edd..f27ab68 100644 --- a/Api.md +++ b/Api.md @@ -1,13 +1,17 @@ The MITREid Connect server has a robust RESTful API that is used to manage various aspects of the server's configuration. In fact, the administration UI is really just a JavaScript application that uses this RESTful API to do its job. +The API may be accessed through an active web session within the application (ie, any JavaScript running on the server itself) or through authorizing a client application through OAuth. + ## Clients -Endpoint: `/api/clients` - Manages all registered clients on the system, both statically and dynamically registered. +Endpoint: **`/api/clients`** + ### GET /api/clients +_Requires **ROLE_USER** or **ROLE_ADMIN** access._ + Get a list of all clients on the system, returns results in `application/json`. ``` @@ -99,6 +103,8 @@ Get a list of all clients on the system, returns results in `application/json`. ### POST /api/clients +_Requires **ROLE_ADMIN** access._ + Create a new client on the system. Message body is an `application/json` object with all client parameters: ``` @@ -172,6 +178,8 @@ The server will return an updated copy of the object in `application/json` forma ### GET /api/clients/{id} +_Requires **ROLE_USER** or **ROLE_ADMIN** access._ + Get information about a specific client identified by {id} in the url, in `application/json` format. For example, the call to `/api/clients/1` would return: @@ -258,6 +266,8 @@ For example, the call to `/api/clients/1` would return: ### PUT /api/clients/{id} +_Requires **ROLE_ADMIN** access._ + Update the information for the client identified by {id} in the URL. The request body must be `application/json` describing the entire client object: ``` @@ -331,12 +341,112 @@ The server will return an updated copy of the object in `application/json` forma ### DELETE /api/clients/{id} +_Requires **ROLE_ADMIN** access._ + Deletes the client with the {id} in the URL. Returns HTTP 200 with an empty page on success. ## Whitelists +Whitelist entries allow an administrator to specify which clients will not cause a prompt a user for authorization under certain circumstances, such as a subset of the scopes for that client. + +Endpoint: **`/api/whitelist`** + +### GET /api/whitelist + +_Requires **ROLE_USER** or **ROLE_ADMIN** access._ + +Get a list of all whitelists on the system, returns results in `application/json`. + +``` +[ + + { + "id": 1, + "creatorUserId": "jricher", + "clientId": "client", + "allowedScopes": [ + "email", + "openid", + "profile" + ] + } + +] +``` + +### POST /api/whitelist + +_Requires **ROLE_ADMIN** access._ + +Create a new whitelist on the system. Message body is an `application/json` object with all information: + +``` +{ + "id": 1, + "creatorUserId": "jricher", + "clientId": "client", + "allowedScopes": [ + "email", + "openid", + "profile" + ] +} +``` + +The server will return an updated copy of the object in `application/json` format as described under **GET /api/whitelist/{id}** on success. + +### GET /api/whitelist/{id} + +_Requires **ROLE_USER** or **ROLE_ADMIN** access._ + +Get information about a specific whitelist identified by {id} in the url, in `application/json` format. + +For example, the call to `/api/whitelist/1` would return: + +``` +{ + "id": 1, + "creatorUserId": "jricher", + "clientId": "client", + "allowedScopes": [ + "email", + "openid", + "profile" + ] +} +``` + +### PUT /api/whitelist/{id} + +_Requires **ROLE_ADMIN** access._ + +Update the information for the whitelist identified by {id} in the URL. The request body must be `application/json` describing the entire whitelist object: + +``` +{ + "id": 1, + "creatorUserId": "jricher", + "clientId": "client", + "allowedScopes": [ + "email", + "openid", + "profile" + ] +} +``` + +The server will return an updated copy of the object in `application/json` format as described under **GET /api/whitelist/{id}** on success. + +### DELETE /api/whitelist/{id} + +_Requires **ROLE_ADMIN** access._ + +Deletes the whitelist with the {id} in the URL. + +Returns HTTP 200 with an empty page on success. + ## Blacklists ## System Scopes