diff --git a/docs/embeddable-uis/element/operation_approval.mdx b/docs/embeddable-uis/element/operation_approval.mdx new file mode 100644 index 00000000..8d66c321 --- /dev/null +++ b/docs/embeddable-uis/element/operation_approval.mdx @@ -0,0 +1,361 @@ +--- +sidebar_position: 2 +title: Operation Approval API +--- +import HelpSupportTile from "@site/src/components/elements/HelpSupportTile.js"; +import ActionContainer from "@site/src/components/elements/ActionContainer.js"; +import ActionTile from "@site/src/components/elements/ActionTile.js"; +import CodeDropdown from "@site/src/components/elements/CodeDropdown.js"; +import FlexWrapper from "@site/src/components/elements/FlexWrapper.js"; +import code from "@site/src/components/elements/codeBlock.json"; + +# Operation Approval API + +The Operation Approval API allows to create operation approvals for specific action in your application. It also assigns relevant moderators to approve or deny user requests based on your decision. + +:::note +You can also find information about the approval Flow API in the [Permit Redoc](https://api.permit.io/v2/redoc#tag/Access-Requests). +::: + +### Initializing Permit + + + {/* If you already use Permit, skip this step. */} + To use Permit Elements, you need to be a **user of Permit**. When starting to use Permit, you will need to + initialize an instance of Permit in your backend logic. This **only needs to be done once**, both to use Permit and Elements. + Remember to copy your `SDK Secret Key` and pass it into the initialized Permit object. + + + +### Server-side Login Route + +To allow your client to `loginAs` themselves and get access to the Permit Element you will need to create a route in your backend server. + +The backend `loginAs` route is matched based on the Authentication methods you have implemented inside your App. +Most applications authenticate using a **Bearer Token** or **Cookies**, but you can also use any other **HTTP Security Header**. +Make sure you use the right code example below depending on your authentication method. + +The `loginAs` function takes two parameters - a unique `userId` you get from your **JWT** (JSON Web Token), and a `tenant_key` or `tenantId`. + +```js +permit.elements.loginAs({ userId, tenant }); +``` + +:::info IMPORTANT +The **user must belong to the tenant** that they will be logged into. If not, you will see a login error saying `USER_NOT_FOUND`. + +If the user gets logged out, they also exit the current tenant specified in the `loginAs` method. If you want to **change tenants** for +a user, you need to **log them out**, and **log them back in** to a different tenant. +::: + +Passing in the tenant is **compulsory** when logging in a user **server-side**. + + + To get the cookie, in the `redirect_url` (that you will get + from the `ticket` object) you will have `get_cookie`. + + + +## API requests + +To use the Approval Request API, follow these steps: + +[Get your `API_SECRET_KEY`](/api/api-with-cli/#get-your-api-key) from the dashboard and [get the current `project_id` and `env_id`](/api/examples/get-project-and-env)
. +Replace `API_SECRET_KEY` with the key from the Permit dashboard, as well as the `project_id` and `env_id` you got from the API in the following commands. + +### Creating an Approval request + +To create a new operation approval, make a POST request to the following with the required data. + +```bash +curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/approval_flow' \ + -H 'cookie: ' + -H 'element_id: ELEMENTS_CONFIG_ID' + -data-raw + { + "access_request_details": { + "tenant": "34f5c98e-f430-457b-a812-92637d0c6fd0", + "resource": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", + }, + "reason": "I need to make transfer for my client", + } \ +``` + +The return operation approval object will look like this: +```json +{ + "requesting_user_id": "1c1e4ada-f282-40e6-b3b7-20b3a51c93b5", + "access_request_details": { + "tenant": "34f5c98e-f430-457b-a812-92637d0c6fd0", + "resource": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", + "resource_instance": "2d98d9f8-e1b7-4f1d-baad-2edbf6fa6c66", + }, + "reason": "I need to make transfer for my client", + "org_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", + "env_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", + "created_at": "2019-08-24T14:15:22Z", + "updated_at": "2019-08-24T14:15:22Z", + "status": null, + "reviewer_user_id": null, + "reviewed_at": null, + "reviewer_comment": null, + "type": "operation_approval" +} +``` +## Reviewer actions: + +### 1. Get an operation approval + +To get a specific operation approval, make a GET request to the following. +```bash +curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/approval_flow/{approval_request_id}' \ + -H 'cookie: ' + -H 'element_id: ELEMENTS_CONFIG_ID' +``` +The return operation approval object will look like this: +```json +{ + "requesting_user_id": "1c1e4ada-f282-40e6-b3b7-20b3a51c93b5", + "access_request_details": { + "tenant": "34f5c98e-f430-457b-a812-92637d0c6fd0", + "resource": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", + "resource_instance": "2d98d9f8-e1b7-4f1d-baad-2edbf6fa6c66", + }, + "reason": "string", + "org_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", + "env_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", + "created_at": "2019-08-24T14:15:22Z", + "updated_at": "2019-08-24T14:15:22Z", + "status": "approved", + "reviewer_user_id": "1b287364-14ff-4b72-8953-b40399093a6f", + "reviewed_at": "2019-08-24T14:15:22Z", + "reviewer_comment": "transfer for a new client", + "type": "operation_approval" +} +``` +### 2. Get all the Approval Requests + +You can filter approval processes by passing the following headers: +- `status` - Status of the operation approval +- `resource` - Resource key of the operation approval +- `resource_instance` - Resource instance key of the operation approval + +To get a list of operation approvals, make the following GET request: + +```bash +curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/approval_flow' \ + -H 'cookie: ' + -H 'element_id: ELEMENTS_CONFIG_ID' + -H 'status: Status of the approval process' + -H 'resource: Resource key of the approval process' + -H 'resource_instance: Resource instance key of the approval process' + -H 'page: Page number of the results to fetch' #Default: 1 + -H 'per_page: The number of results per page (max 100)' #Default: 30 +``` + +The return operation approval object will look like this: +```json +{ + "data": [ + { + "requesting_user_id": "1c1e4ada-f282-40e6-b3b7-20b3a51c93b5", + "access_request_details": { + "tenant": "34f5c98e-f430-457b-a812-92637d0c6fd0", + "resource": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", + "resource_instance": "2d98d9f8-e1b7-4f1d-baad-2edbf6fa6c66", + }, + "reason": "I need to make transfer for my client", + "org_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", + "env_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", + "created_at": "2019-08-24T14:15:22Z", + "updated_at": "2019-08-24T14:15:22Z", + "status": "approved", + "reviewer_user_id": "1b287364-14ff-4b72-8953-b40399093a6f", + "reviewed_at": "2019-08-24T14:15:22Z", + "reviewer_comment": "transfer for a new client", + "type": "operation_approval", + "requesting_user_email": "maya@permit.io", + "requesting_user_first_name": "Maya", + "requesting_user_last_name": "Barak", + "resource_key": "transfer", + "resource_instance_key": "transfer-1", + } + ], + "total_count": 1, + "page_count": 1 +} +``` +:::info Info +Users who are not designated as reviewers will only have visibility into their own operation approvals. +::: + + +### 3. Updating Reviewer details in the operation approval + +To update an operation approval, make the following PATCH request (data is optional): + +```bash +curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/approval_flow/{approval_request_id}/reviewer' \ + -H 'cookie: ' + -H 'element_id: ELEMENTS_CONFIG_ID' + --data-raw + "reviewer_comment": "transfer for a new client", + } \ +``` + +The return approval process object will look like this: +```json +{ + "requesting_user_id": "1c1e4ada-f282-40e6-b3b7-20b3a51c93b5", + "access_request_details": { + "tenant": "34f5c98e-f430-457b-a812-92637d0c6fd0", + "resource": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", + "resource_instance": "2d98d9f8-e1b7-4f1d-baad-2edbf6fa6c66", + }, + "reason": "I need to make transfer for my client", + "org_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", + "env_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", + "created_at": "2019-08-24T14:15:22Z", + "updated_at": "2019-08-24T14:15:22Z", + "status": "approved", + "reviewer_user_id": "1b287364-14ff-4b72-8953-b40399093a6f", + "reviewed_at": "2019-08-24T14:15:22Z", + "reviewer_comment": "transfer for a new client", + "type": "operation_approval" +} +``` + + +### 4. Approve operation approval + +To approve an operation approval, make the following PUT request (data is optional): + +```bash +curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/approval_flow/{approval_request_id}/approve' \ + -H 'cookie: ' + -H 'element_id: ELEMENTS_CONFIG_ID' + --data-raw + { + "reviewer_comment": "transfer for a new client", + }\ +``` + +The return user object will look like this: +```json +{ + "requesting_user_id": "1c1e4ada-f282-40e6-b3b7-20b3a51c93b5", + "access_request_details": { + "tenant": "34f5c98e-f430-457b-a812-92637d0c6fd0", + "resource": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", + "resource_instance": "2d98d9f8-e1b7-4f1d-baad-2edbf6fa6c66", + }, + "reason": "I need to make transfer for my client", + "org_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", + "env_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", + "created_at": "2019-08-24T14:15:22Z", + "updated_at": "2019-08-24T14:15:22Z", + "status": "approved", + "reviewer_user_id": "1b287364-14ff-4b72-8953-b40399093a6f", + "reviewed_at": "2019-08-24T14:15:22Z", + "reviewer_comment": "transfer for a new client", + "type": "operation_approval" +} +``` + +### 5. Deny operation approval + +To deny an operation approval, make the following PUT request (data is optional): + +```bash +curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/approval_flow/{access_request_id}/deny' \ + -H 'cookie: ' + -H 'element_id: ELEMENTS_CONFIG_ID' + --data-raw + "reviewer_comment": "need more info", + }\ +``` + +The return operation approval object will look like this: +```json +{ + "requesting_user_id": "1c1e4ada-f282-40e6-b3b7-20b3a51c93b5", + "access_request_details": { + "tenant": "34f5c98e-f430-457b-a812-92637d0c6fd0", + "resource": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", + "resource_instance": "2d98d9f8-e1b7-4f1d-baad-2edbf6fa6c66", + }, + "reason": "I need to make transfer for my client", + "org_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", + "env_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", + "created_at": "2019-08-24T14:15:22Z", + "updated_at": "2019-08-24T14:15:22Z", + "status": "deny", + "reviewer_user_id": "1b287364-14ff-4b72-8953-b40399093a6f", + "reviewed_at": "2019-08-24T14:15:22Z", + "reviewer_comment": "need more info", + "type": "operation_approval" +} +``` + +## Users actions: + +### 1. Cancel operation approval + +To cancel an operation approval, make the following PUT request: + +```bash +curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/approval_flow/{approval_request_id}/cancel' \ + -H 'cookie: ' + -H 'element_id: ELEMENTS_CONFIG_ID' + --data-raw +{ + "reason": "done onboarding last week", +} \ +``` +The return operation approval object will look like this: +```json +{ + "requesting_user_id": "1c1e4ada-f282-40e6-b3b7-20b3a51c93b5", + "access_request_details": { + "tenant": "34f5c98e-f430-457b-a812-92637d0c6fd0", + "resource": "4d5215ed-38bb-48ed-879a-fdb9ca58522f", + "resource_instance": "2d98d9f8-e1b7-4f1d-baad-2edbf6fa6c66", + }, + "reason": "I need to make transfer for my client", + "org_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", + "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", + "env_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", + "created_at": "2019-08-24T14:15:22Z", + "updated_at": "2019-08-24T14:15:22Z", + "status": "cancel", + "reviewer_user_id": null, + "reviewed_at": null, + "reviewer_comment": null, + "type": "operation_approval" +} +```