# Manage Access Requests

This page describes the `subscription` endpoint, which allows you to view and manage access requests.

{% hint style="info" %}
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
{% endhint %}

## Subscription workflow

1. [Get pending access requests](#get-pending-access-requests).
2. [Approve access requests](#approve-access-requests).
3. [Deny access requests](#deny-access-requests).

## Get pending access requests

| Method | Path                                                                                                    | Purpose                                                                                        |
| ------ | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| GET    | [`/subscription/getPendingRequestsForUser`](#get-pending-access-requests-you-can-approve)               | Get pending access requests the calling user can approve.                                      |
| GET    | [`/subscription/requestInfo/{modelType}/{modelId}`](#get-pending-access-requests-for-a-specified-model) | Get pending request information for specified model and requesting user (or specified entity). |

### Get pending access requests you can approve

<mark style="color:green;">`GET`</mark> `/subscription/getPendingRequestsForUser`

Get pending access requests the calling user can approve.

#### Query parameters

| Attribute     | Description                                                                      | Required |
| ------------- | -------------------------------------------------------------------------------- | -------- |
| groupByEntity | `boolean` If `true`, group request results by user/group.                        | No       |
| profileId     | `integer` Match against profile ID.                                              | No       |
| groupId       | `integer` Match against group ID.                                                | No       |
| name          | `string` A partial name to match against user or group names.                    | No       |
| email         | `string` A partial email address to match against user or group email addresses. | No       |
| modelName     | `string` A partial name to match against model names.                            | No       |
| modelTypes    | `array[string]` Model types to include.                                          | No       |
| size          | `integer` The max number of matches to return. **Default 15**.                   | No       |
| sortField     | `string` The field to sort results on. Defaults to name.                         | No       |
| sortOrder     | `string` The order that the results will be sorted in. **Default `asc`**.        | No       |
| offset        | `integer` Offset to start returning values.                                      | No       |

#### Response parameters

| Attribute | Description                                             |
| --------- | ------------------------------------------------------- |
| hits      | `array` Metadata details regarding the access requests. |
| count     | `integer` The number of access requests.                |

#### Request example

The following request gets pending access requests the calling user can approve.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/subscription/getPendingRequestsForUser?size=15&sortOrder=asc
```

#### Response example

```json
{
  "hits": [
    {
      "id": 652,
      "createdAt": "2021-10-14T14:25:16.509Z",
      "metadata": {},
      "model": {
        "type": "datasource",
        "id": 544,
        "name": "Gp Toolkit  Gp Is Append Only"
      },
      "entity": {
        "type": "profile",
        "id": 2,
        "name": "First Last",
        "email": "first.last@immuta.com"
      },
      "approvals": [
        {
          "requiredPermission": "OWNER",
          "state": "pending",
          "approverId": null,
          "ownerModelId": null,
          "approver": null,
          "ownerModelName": null
        }
      ]
    }
  ],
  "count": 1
}
```

### Get pending access requests for a specified model

<mark style="color:green;">`GET`</mark> `/subscription/requestInfo/{modelType}/{modelId}`

Get pending request information for specified model and requesting user (or specified entity).

#### Query parameters

| Attribute | Description                                                                                  | Required |
| --------- | -------------------------------------------------------------------------------------------- | -------- |
| modelType | `string` The model that a pending request is out for. Options are `datasource` or `project`. | **Yes**  |
| modelId   | `integer` The data source or project ID.                                                     | **Yes**  |
| profileId | `integer` A user ID if you want to get pending requests for another user.                    | No       |
| groupId   | `integer` A group ID if you want to get pending requests for a whole group.                  | No       |

#### Response parameters

| Attribute | Description                                                                                                                                                                           |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| records   | `array` Details about each of the pending access requests, including `subscriptionId`, `requiredPermission`, `state`, `approverId`, `ownerModelId`, `approver`, and `ownerModelName`. |

#### Request example

The following request gets pending access requests for the data source with the ID `6` for the current user.

```shell
curl -X 'GET' \
  'https://demo.immuta.com/subscription/requestInfo/datasource/6' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 2533855fddf14b688df4483a30e7d57f'
```

#### Response example

```json
{
  "records": [
    {
      "subscriptionId": 36,
      "requiredPermission": "OWNER",
      "state": "pending",
      "approverId": null,
      "ownerModelId": null,
      "approver": null,
      "ownerModelName": null
    }
  ]
}
```

## Approve access requests

| Method | Path                                                          | Purpose                            |
| ------ | ------------------------------------------------------------- | ---------------------------------- |
| POST   | [`/subscription/approve`](#approve-specified-access-requests) | Approve specified access requests. |
| POST   | [`/subscription/approve/bulk`](#approve-bulk-access-requests) | Bulk approve access requests.      |

### Approve specified access requests

<mark style="color:green;">`POST`</mark> `/subscription/approve`

Approve specified access requests.

#### Payload parameters

| Attribute  | Description                                              | Required |
| ---------- | -------------------------------------------------------- | -------- |
| id         | `integer` The subscription ID of the request to approve. | **Yes**  |
| expiration | `date` The date to expire this user's access.            | No       |

#### Response parameters

| Attribute | Description                                                                                                         |
| --------- | ------------------------------------------------------------------------------------------------------------------- |
| id        | `integer` If the request fails, the response includes the ID of the access request.                                 |
| model     | `array[object]` If the request fails, the response includes details about the data source or project.               |
| entity    | `array[object]` If the request fails, the response includes details about the user making the subscription request. |

#### Request example

The following request approves the subscription request.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.com/subscription/approve
```

#### Payload example

```json
{
  "requests": [
    {
      "id": 652,
      "expiration": "2021-10-14"
    }
  ]
}
```

#### Response example

```json
{
  "failures": []
}
```

### Approve bulk access requests

<mark style="color:green;">`POST`</mark> `/subscription/approve/bulk`

Bulk approve access requests.

#### Payload parameters

| Attribute  | Description                                                                                                                                                                                                                                 | Required |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| requestIds | `integer` A list of the access request IDs to be approved. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all approval requests. | **Yes**  |
| id         | `integer` The ID for the `type`. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all approval requests.                           | **Yes**  |
| type       | `string` The type of ID: `profile`. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all approval requests.                        | **Yes**  |

#### Response parameters

| Attribute | Description                                                                      |
| --------- | -------------------------------------------------------------------------------- |
| success   | `boolean` If `true`, all of the access requests have been successfully approved. |

#### Request example

The following request approves all of the subscription requests.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.com/subscription/approve/bulk
```

#### Payload example

```json
{
  "id": 4,
  "type": "profile"
}
```

#### Response example

```json
{
  "success": true
}
```

## Deny access requests

| Method | Path                                                    | Purpose                         |
| ------ | ------------------------------------------------------- | ------------------------------- |
| POST   | [`/subscription/deny`](#deny-specified-access-requests) | Deny specified access requests. |
| POST   | [`/subscription/deny/bulk`](#deny-bulk-access-requests) | Bulk deny access requests.      |

### Deny specified access requests

<mark style="color:green;">`POST`</mark> `/subscription/deny`

Deny specified access requests.

#### Payload parameters

| Attribute       | Description                                                                  | Required |
| --------------- | ---------------------------------------------------------------------------- | -------- |
| id              | `integer` The subscription ID of the request to deny.                        | **Yes**  |
| denialReasoning | `string` The reason the user is denied access to the data source or project. | **Yes**  |

#### Response parameters

| Attribute | Description                                                                                                         |
| --------- | ------------------------------------------------------------------------------------------------------------------- |
| id        | `integer` If the request fails, the response includes the ID of the access request.                                 |
| model     | `array[object]` If the request fails, the response includes details about the data source or project.               |
| entity    | `array[object]` If the request fails, the response includes details about the user making the subscription request. |

#### Request example

The following request denies the subscription request.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.com/subscription/deny
```

#### Payload example

```json
{
  "requests": [
    {
      "id": 652,
      "denialReasoning": "testdenial"
    }
  ]
}
```

#### Response example

```json
{
  "failures": []
}
```

### Deny bulk access requests

<mark style="color:green;">`POST`</mark> `/subscription/deny/bulk`

Bulk deny access requests.

#### Payload parameters

| Attribute       | Description                                                                                                                                                                                                                               | Required |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| requestIds      | `integer` A list of the access request IDs to be approved. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all denial requests. | **Yes**  |
| id              | `integer` The ID for the `type` you select. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all denial requests.                | **Yes**  |
| type            | `string` The type of ID: `profile`. If `requestIds` is provided, jobs will only be created for the IDs listed. Otherwise, the `id` and `type` values will be used to find and create jobs for all denial requests.                        | **Yes**  |
| denialReasoning | `string` The reason that you are denying the access requests.                                                                                                                                                                             | **Yes**  |

#### Response parameters

| Attribute | Description                                                                    |
| --------- | ------------------------------------------------------------------------------ |
| success   | `boolean` If `true`, all of the access requests have been successfully denied. |

#### Request example

The following request with the payload below denies the subscription requests with the IDs `40` and `41`.

```shell
curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.com/subscription/deny/bulk
```

#### Payload example

```json
{
  "requestIds": [
    40,
    41
  ],
  "denialReasoning": "The users do not have the right attributes."
}
```

#### Response example

```json
{
  "success": true
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.immuta.com/2024.2/developer-guides/api-intro/immuta-v1-api/manage-data-access/subscription.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.