Skip to main content
Version: 2.0.0

Access Request API

The Access Request API allows 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.

note

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

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 Access Requests 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 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/{project_id}/{env_id}/access_requests' \
  -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",
        "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/{project_id}/{env_id}/access_requests/{access_request_id}' \
  -H 'cookie: <COOKIE FROM LOGIN>'
  -H 'element_id: ELEMENTS_CONFIG_ID'

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/{project_id}/{env_id}/access_requests' \
  -H 'cookie: <COOKIE FROM LOGIN>'
  -H 'element_id: ELEMENTS_CONFIG_ID'
  -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/{project_id}/{env_id}/access_requests/{access_request_id}/reviewer' \
  -H 'cookie: <COOKIE FROM LOGIN>'
  -H 'element_id: ELEMENTS_CONFIG_ID'
  --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/{project_id}/{env_id}/access_requests/{access_request_id}/approve' \
  -H 'cookie: <COOKIE FROM LOGIN>'
  -H 'element_id: ELEMENTS_CONFIG_ID'
  --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/{project_id}/{env_id}/access_requests/{access_request_id}/deny' \
  -H 'cookie: <COOKIE FROM LOGIN>'
  -H 'element_id: ELEMENTS_CONFIG_ID'
  --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/{project_id}/{env_id}/access_requests/{access_request_id}/cancel' \
  -H 'cookie: <COOKIE FROM LOGIN>'
  -H 'element_id: ELEMENTS_CONFIG_ID'
  --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,
}

Contents