1 of 1

Manage Access Requests

Subscription API reference guide

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

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

Get pending access requests

Method

Path

Purpose

GET

Get pending access requests the calling user can approve.

GET

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

Get pending access requests you can approve

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.

profileId

integer Match against profile ID.

groupId

integer Match against group ID.

name

string A partial name to match against user or group names.

string A partial email address to match against user or group email addresses.

modelName

string A partial name to match against model names.

modelTypes

array[string] Model types to include.

size

integer The max number of matches to return. Default 15.

sortField

string The field to sort results on. Defaults to name.

sortOrder

string The order that the results will be sorted in. Default asc.

offset

integer Offset to start returning values.

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
}

Get pending access 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.

groupId

integer A group ID if you want to get pending requests for a whole group.

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.

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 access requests

Method

Path

Purpose

POST

Approve specified access requests.

POST

Bulk approve access requests.

Approve specified access requests

POST /subscription/approve

Approve specified access requests.

Payload parameters

Attribute

Description

Required

integer The subscription ID of the request to approve.

Yes

expiration

date The date to expire this user's access.

Response parameters

Attribute

Description

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 example

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

Response example

{
  "failures": []
}

Approve bulk access requests

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

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.

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 access requests

Method

Path

Purpose

POST

Deny specified access requests.

POST

Bulk deny access requests.

Deny specified access requests

POST /subscription/deny

Deny specified access requests.

Payload parameters

Attribute

Description

Required

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

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 example

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

Response example

{
  "failures": []
}

Deny bulk access requests

POST /subscription/deny/bulk

Bulk deny access requests.

Payload parameters

Attribute

Description

Required

requestIds

Yes

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

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.

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
}

Manage Access Requests

Subscription API reference guide

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

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

Subscription workflow

Get pending access requests.
Approve access requests.
Deny access requests.

Get pending access requests

Method

Path

Purpose

GET

Get pending access requests the calling user can approve.

GET

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

Get pending access requests you can approve

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.

profileId

integer Match against profile ID.

groupId

integer Match against group ID.

name

string A partial name to match against user or group names.

string A partial email address to match against user or group email addresses.

modelName

string A partial name to match against model names.

modelTypes

array[string] Model types to include.

size

integer The max number of matches to return. Default 15.

sortField

string The field to sort results on. Defaults to name.

sortOrder

string The order that the results will be sorted in. Default asc.

offset

integer Offset to start returning values.

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
}

Get pending access 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.

groupId

integer A group ID if you want to get pending requests for a whole group.

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.

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 access requests

Method

Path

Purpose

POST

Approve specified access requests.

POST

Bulk approve access requests.

Approve specified access requests

POST /subscription/approve

Approve specified access requests.

Payload parameters

Attribute

Description

Required

integer The subscription ID of the request to approve.

Yes

expiration

date The date to expire this user's access.

Response parameters

Attribute

Description

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 example

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

Response example

{
  "failures": []
}

Approve bulk access requests

POST /subscription/approve/bulk

Bulk approve access requests.

Payload parameters

Attribute

Description

Required

requestIds

Yes

type

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.

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 access requests

Method

Path

Purpose

POST

Deny specified access requests.

POST

Bulk deny access requests.

Deny specified access requests

POST /subscription/deny

Deny specified access requests.

Payload parameters

Attribute

Description

Required

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

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 example

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

Response example

{
  "failures": []
}

Deny bulk access requests

POST /subscription/deny/bulk

Bulk deny access requests.

Payload parameters

Attribute

Description

Required

requestIds

Yes

type

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.

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
}