Skip to content

You are viewing documentation for Immuta version 2022.1.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

Subscription API

Audience: Data Owners and Project Owners

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

Note

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 access requests.
  2. Approve-access-requests.
  3. Deny-access-requests.

Get Pending Access Requests

Endpoint

Method Path Purpose
GET /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.

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

{
  "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
}

Approve Access Requests

Endpoint

Method Path Purpose
POST /subscription/approve Approve specified access requests.

Query Parameters

None.

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.

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

Payload Request Example

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

Response Example

{
  "failures": []
}

Deny Access Requests

Endpoint

Method Path Purpose
POST /subscription/deny Deny specified access requests.

Query Parameters

None.

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.

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

Payload Request Example

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

Response Example

{
  "failures": []
}