Merge pull request #348 from permitio/maya/per-9916-approval-process-…

…request-api add docs for approval flow api
permitio · Jun 6, 2024 · b6688ac · b6688ac
2 parents f12dd33 + ddb7797
commit b6688ac
Showing 1 changed file with 361 additions and 0 deletions.
diff --git a/docs/embeddable-uis/element/operation_approval.mdx 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
+
+<CodeDropdown
+	number="1"
+	title=""
+	server
+	code={[code.initialize_node, code.initialize_python, code.initialize_dotnet, code.initialize_java]}
+	language={["javascript", "python", "c", "java"]}
+	languages={["Node", "Python", "Dotnet", "Java"]}
+	open
+>
+	{/* 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.
+
+</CodeDropdown>
+
+### 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**.
+
+<CodeDropdown
+	title="Using Cookies"
+	server
+	code={[
+		code.cookies_node,
+		code.cookies_python,
+		code.cookies_dotnet,
+		code.cookies_java,
+	]}
+	language={["javascript", "python", "c", "java"]}
+	languages={["Node", "Python", "Dotnet", "Java"]}
+>
+    To get the cookie, in the `redirect_url` (that you will get
+    from the `ticket` object) you will have `get_cookie`.
+</CodeDropdown>
+
+
+## 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)<br/>.
+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: <COOKIE FROM LOGIN>'
+  -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: <COOKIE FROM LOGIN>'
+  -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: <COOKIE FROM LOGIN>'
+  -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: <COOKIE FROM LOGIN>'
+  -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: <COOKIE FROM LOGIN>'
+  -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: <COOKIE FROM LOGIN>'
+  -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: <COOKIE FROM LOGIN>'
+  -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"
+}
+```