Manage Subscription Requests

Subscription API reference guide

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

Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.

Subscription workflow

1. Get pending subscription requests.

2. Approve subscription requests.

3. Deny subscription requests.

Get pending subscription requests

Method	Path	Purpose
GET	/subscription/getPendingRequestsForUser	Get pending subscription requests the calling user can approve.
GET	/subscription/requestInfo/{modelType}/{modelId}	Get pending request information for specified model and requesting user (or specified entity).

Get pending subscription requests you can approve

GET /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.

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

{
  "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": "[email protected]"
      },
      "approvals": [
        {
          "requiredPermission": "OWNER",
          "state": "pending",
          "approverId": null,
          "ownerModelId": null,
          "approver": null,
          "ownerModelName": null
        }
      ]
    }
  ],
  "count": 1
}

Get pending subscription requests for a specified model

GET /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.

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

Response example

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

Approve subscription requests

Method	Path	Purpose
POST	/subscription/approve	Approve specified subscription requests.
POST	/subscription/approve/bulk	Bulk approve subscription requests.

Approve specified subscription requests

POST /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.

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

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

Response example

{
  "failures": []
}

Approve bulk subscription requests

POST /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.

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

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

Response example

{
  "success": true
}

Deny subscription requests

Method	Path	Purpose
POST	/subscription/deny	Deny specified subscription requests.
POST	/subscription/deny/bulk	Bulk deny subscription requests.

Deny specified subscription requests

POST /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.

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

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

Response example

{
  "failures": []
}

Deny bulk subscription requests

POST /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.

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

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

Response example

{
  "success": true
}