# Manage Subscription Requests

This page describes the `subscription` endpoint, which allows you to view and manage subscription requests on data sources and projects.

{% 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 subscription requests](#get-pending-subscription-requests).
2. [Approve subscription requests](#approve-subscription-requests).
3. [Deny subscription requests](#deny-subscription-requests).

## Get pending subscription requests

<table><thead><tr><th>Method</th><th width="495">Path</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><a href="#get-pending-subscription-requests-you-can-approve"><mark style="color:blue;"><code>/subscription/getPendingRequestsForUser</code></mark></a></td><td>Get pending subscription requests the calling user can approve.</td></tr><tr><td>GET</td><td><a href="#get-pending-subscription-requests-for-a-specified-model"><mark style="color:blue;"><code>/subscription/requestInfo/{modelType}/{modelId}</code></mark></a></td><td>Get pending request information for specified model and requesting user (or specified entity).</td></tr></tbody></table>

### Get pending subscription requests you can approve

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

Get pending subscription 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 subscription requests. |
| count     | `integer` The number of subscription requests.                |

#### Request example

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

```bash
curl \
    --request GET \
    --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 subscription 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 subscription requests, including `subscriptionId`, `requiredPermission`, `state`, `approverId`, `ownerModelId`, `approver`, and `ownerModelName`. |

#### Request example

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

```bash
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 subscription requests

<table><thead><tr><th>Method</th><th width="337">Path</th><th>Purpose</th></tr></thead><tbody><tr><td>POST</td><td><a href="#approve-specified-subscription-requests"><mark style="color:blue;"><code>/subscription/approve</code></mark></a></td><td>Approve specified subscription requests.</td></tr><tr><td>POST</td><td><a href="#approve-bulk-subscription-requests"><mark style="color:blue;"><code>/subscription/approve/bulk</code></mark></a></td><td>Bulk approve subscription requests.</td></tr></tbody></table>

### Approve specified subscription requests

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

Approve specified subscription requests.

**Requirement**: `AUDIT` permission, `GOVERNANCE` permission, `USER_ADMIN` permission, or you must be the owner of the data source, depending on the subscription policy

#### 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 subscription 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.

```bash
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 subscription requests

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

Bulk approve subscription requests.

**Requirement**: `AUDIT` permission, `GOVERNANCE` permission, `USER_ADMIN` permission, or you must be the owner of the data source, depending on the subscription policy

#### Payload parameters

| Attribute  | Description                                                                                                                                                                                                                                       | Required |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| requestIds | `integer` A list of the subscription 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 subscription requests have been successfully approved. |

#### Request example

The following request approves all of the subscription requests.

```bash
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 subscription requests

<table><thead><tr><th>Method</th><th width="267">Path</th><th>Purpose</th></tr></thead><tbody><tr><td>POST</td><td><a href="#deny-specified-subscription-requests"><mark style="color:blue;"><code>/subscription/deny</code></mark></a></td><td>Deny specified subscription requests.</td></tr><tr><td>POST</td><td><a href="#deny-bulk-subscription-requests"><mark style="color:blue;"><code>/subscription/deny/bulk</code></mark></a></td><td>Bulk deny subscription requests.</td></tr></tbody></table>

### Deny specified subscription requests

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

Deny specified subscription requests.

**Requirement**: `AUDIT` permission, `GOVERNANCE` permission, `USER_ADMIN` permission, or you must be the owner of the data source, depending on the subscription policy

#### 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 subscription 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.

```bash
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 subscription requests

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

Bulk deny subscription requests.

**Requirement**: `AUDIT` permission, `GOVERNANCE` permission, `USER_ADMIN` permission, or you must be the owner of the data source, depending on the subscription policy

#### Payload parameters

| Attribute       | Description                                                                                                                                                                                                                                     | Required |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| requestIds      | `integer` A list of the subscription 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 subscription requests.                                                                                                                                                                             | **Yes**  |

#### Response parameters

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

#### Request example

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

```bash
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
}
```