Skip to main content
Version: 2.0.0

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 find more details about the Approval Flow API in the Permit Redoc. Additionally, you can explore the UI documentation for the Operation Approval Element.

Check out our demo application that uses the Operation Approval API.

Initializing Permit​

1Server-side

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.

Node
Python
Dotnet
Java
1 2 3 4 const { Permit } = require("permitio"); const permit = new Permit( {token: permit_key_SECRET} );

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.

permit.elements.loginAs({ userId, tenant });
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.

Using CookiesServer-side

API requests​

To use the Approval Request API, follow these steps:

Get your API_SECRET_KEY from the dashboard and get the current project_id and env_id
. 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.

curl -X POST \
 'https://api.permit.io/v2/elements/{proj_id}/{env_id}/config/{elements_config_id}/operation_approval' \
  -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:

{
    "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.

curl 'https://api.permit.io/v2/elements/{proj_id}/{env_id}/config/{elements_config_id}/operation_approval/{operation_approval_id}' \
  -H 'cookie: <COOKIE FROM LOGIN>'
  -H 'element_id: ELEMENTS_CONFIG_ID'

The return operation approval object will look like this:

{
    "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:

curl 'https://api.permit.io/v2/elements/{proj_id}/{env_id}/config/{elements_config_id}/operation_approval' \
  -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:

{
    "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

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):

curl -X PATCH \
 'https://api.permit.io/v2/elements/{proj_id}/{env_id}/config/{elements_config_id}/operation_approval/{operation_approval_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:

{
    "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):

curl -X PUT \
 'https://api.permit.io/v2/elements/{proj_id}/{env_id}/config/{elements_config_id}/operation_approval/{operation_approval_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:

{
    "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):

curl -X PUT \
'https://api.permit.io/v2/elements/{proj_id}/{env_id}/config/{elements_config_id}/operation_approval/{operation_approval_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:

{
    "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:

curl -X PUT \
 'https://api.permit.io/v2/elements/{proj_id}/{env_id}/config/{elements_config_id}/operation_approval/{operation_approval_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:

{
    "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"
}

Contents