Version: 2.0.0

Access Request- Use API KEY for API Only

info

This API is designed for use with access requests via the API, without embedding UI components. If you’re using access requests as part of Permit Elements, you should use the Access Request Element instead.

The Access Request API allows you to create access requests for specific roles or resource instances. It also assigns relevant moderators to approve or deny user requests based on your decision.

To use this API, you need the API_SECRET_KEY from the dashboard, along with the project_id and env_id from the API.

Additionally, to retrieve the user viewer context, you must pass the user identifier and tenant identifier.

note

You can also find information about the Access Requests API in the Permit Redoc.

API requests

info

Please note that the elements_config_id refers to the ID of the user management element that is linked to the access request element.

To use the Access Requests API, follow these steps:

Creating an Access Request

To create a new access request, make a POST request to the following with the required data.

curl 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/access_requests/{elements_config_id}/user/{user_ident}/tenant/{tenant_ident}' \
    -H 'authorization: Bearer API_SECRET_KEY' \
  -data-raw
 {
    "access_request_details": {
        "tenant": "34f5c98e-f430-457b-a812-92637d0c6fd0",
        "resource": "4d5215ed-38bb-48ed-879a-fdb9ca58522f",
        "resource_instance": "2d98d9f8-e1b7-4f1d-baad-2edbf6fa6c66",
        "role": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
    },
    "reason": "done onboarding",
 } \

The return access request 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",
        "role": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
    },
    "reason": "done onboarding",
    "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,
}

Info

The user who creates the access request must be in the tenant that the access request is for.

Reviewer actions:

1. Get an Access Request

To get a specific access request, make a GET request to the following.

curl 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/access_requests/{elements_config_id}/user/{user_ident}/tenant/{tenant_ident}/{access_request_id}' \
    -H 'authorization: Bearer API_SECRET_KEY'  \

The return access request 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",
        "role": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
    },
    "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": "new employee",
}

2. Get all the Access Requests

You can filter access requests by passing the following headers:

status - Status of the access request
tenant - Tenant key of the access request
role - Role key of the access request
resource - Resource key of the access request
resource_instance - Resource instance key of the access request

To get a list of access requests, make the following GET request:

curl 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/access_requests/{elements_config_id}/user/{user_ident}/tenant/{tenant_ident}' \
    -H 'authorization: Bearer API_SECRET_KEY'  \
  -H 'status: Status of the access request' \
  -H 'tenant: Tenant key of the access request' \
  -H 'role: Role key of the access request' \
  -H 'resource: Resource key of the access request' \
  -H 'resource_instance: Resource instance key of the access request' \
  -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 access request 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",
                "role": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
            },
            "reason": "done onboarding",
            "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": "new employee",
        }
    ],
    "total_count": 1,
    "page_count": 1
}

Info

Users who are not designated as reviewers will only have visibility into their own access requests.

3. Updating Reviewer details in the Access Request

To update an access request, make the following PATCH request (data is optional):

curl 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/access_requests/{elements_config_id}/user/{user_ident}/tenant/{tenant_ident}/{access_request_id}/reviewer' \
    -H 'authorization: Bearer API_SECRET_KEY'  \
  --data-raw
     "reviewer_comment": "new employee",
     "role": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
 } \

The return access request 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",
        "role": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
    },
    "reason": "done onboarding",
    "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": "new employee",
}

4. Approve Access Request

To approve an access request, make the following PUT request (data is optional):

curl 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/access_requests/{elements_config_id}/user/{user_ident}/tenant/{tenant_ident}/{access_request_id}/approve' \
    -H 'authorization: Bearer API_SECRET_KEY'  \
  --data-raw
 {
     "reviewer_comment": "new employee",
 }\

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",
        "role": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
    },
    "reason": "done onboarding",
    "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": "new employee",
}

5. Deny Access Request

To deny an access request, make the following PUT request (data is optional):

curl 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/access_requests/{elements_config_id}/user/{user_ident}/tenant/{tenant_ident}/{access_request_id}/deny' \
    -H 'authorization: Bearer API_SECRET_KEY'  \
  --data-raw
     "reviewer_comment": "need more info",
 }\

The return access request 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",
        "role": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
    },
    "reason": "done onboarding",
    "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",
}

Users actions:

1. Cancel Access Request

To cancel an access request, make the following PUT request:

curl 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/access_requests/{elements_config_id}/user/{user_ident}/tenant/{tenant_ident}/{access_request_id}/cancel' \
    -H 'authorization: Bearer API_SECRET_KEY'  \
  --data-raw
{
    "reason": "done onboarding last week",
} \

The return access request 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",
        "role": "ac4e70c8-d5be-48af-93eb-760f58fc91a9",
    },
    "reason": "done onboarding",
    "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,
}

Access Request- Use API KEY for API Only

API requests​

Creating an Access Request​

Reviewer actions:​

1. Get an Access Request​

2. Get all the Access Requests​

3. Updating Reviewer details in the Access Request​

4. Approve Access Request​

5. Deny Access Request​

Users actions:​

1. Cancel Access Request​

Contents

API requests

Creating an Access Request

Reviewer actions:

1. Get an Access Request

2. Get all the Access Requests

3. Updating Reviewer details in the Access Request

4. Approve Access Request

5. Deny Access Request

Users actions:

1. Cancel Access Request