Access Data Sources and Manage Requests

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

Endpoints and methods

Method	Endpoint	Description
POST	/dataSource/subscribe	Subscribe to a data source.
POST	/dataSource/{dataSourceId}/access	Add a user to a specific data source.
GET	/dataSource/tasks/pending	Get all pending tasks for this user and pending tasks this user has created.
GET	/dataSource/{dataSourceId}/tasks	Returns all tasks the user has made, can approve or deny, or validate for this data source.
PUT	/dataSource/{dataSourceId}/access/{subscriptionId}	Change user status for a specific data source.

POST /dataSource/subscribe

Subscribe to a data source.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.com/dataSource/subscribe?dataSourceId=22

Payload example

{
  "dataSourceIds": [
    22
  ],
  "metadata": {},
  "approvals": [
    {
      "requiredPermission": "Owner",
      "specificApproverRequired": false,
      "specificApprover": 2,
      "ownerModelId": 23
    }
  ],
  "groupId": 12
}

Query parameters

Attribute	Description	Required
dataSourceId	integer Data source ID number.	Yes

Payload parameters

Attribute	Description	Required
dataSourceIds	array The ID of the data source the user is subscribing to.	No
approvals	array Includes details about the subscription policy on the data source: requiredPermission, specificApproverRequired, specificApprover, and ownerModelId.	No

Response

Returns subscription results for the requested data source.

Attribute	Description
inError	array Subscription requests that failed.
success	array Subscription requests that succeeded.

{
  "inError": [],
  "success": [{
    "id": 64,
    "modelId": "22",
    "modelType": "datasource",
    "state": "subscribed",
    "metadata": {},
    "admin": null,
    "denialReasoning": null,
    "profile": 2,
    "group": null,
    "expiration": null,
    "acknowledgeRequired": false,
    "createdAt": "2021-08-26T16:36:09.587Z",
    "updatedAt": "2021-08-26T16:36:09.587Z",
    "approved": true
  }]
}

POST /dataSource/{dataSourceId}/access

Add a user to a specific data source. Requestors cannot add themselves to a data source. To request access to a data source, use the /dataSource/subscribe endpoint.

Required: The global GOVERNANCE permission or be the data source owner

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

Payload example

{
  "profileId": 3,
  "state": "subscribed"
}

Path parameters

Attribute	Description	Required
dataSourceId	integer The data source ID.	Yes

Payload parameters

Attribute	Description	Required
state	string The status of the user: subscribed, owner, expert, or ingest.	Yes
profileId	integer The profile ID of the user being added to the data source.	Yes
groupId	integer The ID of the group being added to the data source.	No
approvals	array Details about the user approving access: requiredPermission, specificApproverRequired, and specificApprover.	No
expiration	date The date the user's data source subscription ends.	No

Response

Returns the subscription record for the added user.

Attribute	Description
id	integer The user's subscription ID.
modelId	integer The model ID.
modelType	string The Immuta component to add the user to: datasource or project.
state	string The user's data source role, such as subscribed.
denialReasoning	string If the user was denied access, the reason for denial.
profile	integer The user's profile ID.
group	integer If a group was added, the group ID.
expiration	date The date the user's subscription to the data source will expire.
acknowledgeRequired	boolean If the data source is associated with a project, this value will be true if the user needs to confirm they have read the project acknowledgement.
createdAt	timestamp The date and time of creation.
updatedAt	timestamp The date and time of update.
approved	boolean When true, the user's request has been approved.

{
  "id": 19,
  "modelId": "1",
  "modelType": "datasource",
  "state": "subscribed",
  "metadata": null,
  "admin": 2,
  "denialReasoning": null,
  "profile": 3,
  "group": null,
  "expiration": null,
  "acknowledgeRequired": false,
  "createdAt": "2021-09-21T14:24:12.528Z",
  "updatedAt": "2021-09-21T14:24:12.528Z",
  "approved": true
}

GET /dataSource/tasks/pending

Get all pending tasks for this user and pending tasks this user has created.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://your-immuta-url.com/dataSource/tasks/pending

Query parameters

Attribute	Description	Required
searchText	string If specified, will filter results using the specified string.	No
searchModel	string Will filter the results by model type: dataSource or schemaEvolution.	No
offset	integer The number of results to skip (for paging).	No
size	integer The number of results to return per page.	No
schemaEvolutionConnectionString	string The schema evolution connection string to filter by.	No
countBySchemaEvolution	boolean Iftrue, will only return the number of tasks, grouped by schema evolution.	No
countByDataSource	boolean Iftrue, will only return the number of tasks, grouped by data source.	No
countOnly	boolean When true, will only return a count of the pending tasks.	No
groupByDataSource	boolean If true, will return the results as an array of { dataSourceId: , rows: }.	No
types	Array[string] Filters the results by the type of task: dataSourceCreated, columnAdded, columnDeleted, or columnTypeChanged. The dataSourceCreated, columnAdded, columnDeleted, and columnTypeChanged tasks are only created if a policy that contains the New tag is active and schema monitoring or object sync identifies a change in the remote platform.	No

Response

Returns incoming and outgoing pending tasks.

Attribute	Description
outgoing	array Includes details of the tasks or requests created by the user, such as the count, type, and targetEmails.
incoming	array Includes details about the tasks received by the user, such as the count, type, and targetEmails.

{
  "outgoing": [],
  "incoming": [{
    "fullCount": 1,
    "dataSource": {
      "id": 11,
      "name": "Public Customer"
    },
    "isOutgoing": false,
    "rows": [{
      "id": 1,
      "state": "pending",
      "type": "columnAdded",
      "reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Customer\"",
      "targetNames": [
        "Katie"
      ],
      "targetEmails": [
        "[e-mail]"
      ],
      "requester": {
        "name": "Immuta System Account",
        "id": 1,
        "email": null
      },
      "dataSource": {
        "id": 11,
        "name": "Public Customer"
      },
      "createdAt": "2024-08-06T14:37:09.279+00:00",
      "metadata": {
        "colName": "org",
        "colType": "VARCHAR(16777216)"
      },
      "isOutgoing": false
    }]
  }]
}

GET /dataSource/{dataSourceId}/tasks

Returns all tasks the user has made, can approve or deny, or validate for this data source.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://your-immuta-url.com/dataSource/23/tasks?sortOrder=desc

Path parameters

Attribute	Description	Required
dataSourceId	integer The data source ID.	Yes

Query parameters

Attribute	Description	Required
states	Array[string] The state of the tasks: pending or completed.	No
targetProfileId	integer Only returns tasks where the target user has this profile ID.	No
requestingUserProfileId	integer Only returns tasks where the requesting user has this profile ID.	No
profileId	integer Returns tasks where either the target or requesting user has this profile ID.	No
searchText	string A string used to filter returned users. The query is executed with a wildcard prefix and suffix.	No
searchModel	string A string used to determine how results should be filtered using searchText.	No
types	Array[string] The type of task: dataSourceCreated, columnAdded, columnDeleted, or columnTypeChanged. The dataSourceCreated, columnAdded, columnDeleted, and columnTypeChanged tasks are only created if a policy that contains the New tag is active and schema monitoring or a object sync identifies a change in the remote platform.	No
size	integer The number of results to return.	No
offset	integer The number of results to skip (for paging).	No
sortField	string The field by which to sort the result set.	No
sortOrder	string The order in which to sort the results. The default is desc.	No
countOnly	boolean If true, will only return the number of tasks.	No

Response

Returns matching tasks for the specified data source.

Attribute	Description
hits	array Includes details about each task, such as the id, state, type, and requestor.
count	integer The total number of tasks.

{
  "hits": [
    {
      "fullCount": 2,
      "id": 6,
      "state": "completed",
      "type": "columnAdded",
      "reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Customer\"",
      "targetNames": [
        "John"
      ],
      "targetEmails": [
        "[e-mail]"
      ],
      "requester": {
        "name": "Immuta System Account",
        "id": 1
      },
      "dataSource": {
        "id": 11,
        "name": "Public Customer"
      },
      "createdAt": "2021-10-12T15:48:23.095Z"
    },
    {
      "fullCount": 2,
      "id": 7,
      "state": "completed",
      "type": "columnAdded",
      "reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Fake Medical Claims 2017\"",
      "targetNames": [
        "John"
      ],
      "targetEmails": [
        "[e-mail]"
      ],
      "requester": {
        "name": "Immuta System Account",
        "id": 1
      },
      "dataSource": {
        "id": 3,
        "name": "Public Fake Medical Claims 2017"
      },
      "createdAt": "2021-10-12T18:56:22.954Z"
    }
  ],
  "count": 2
}

PUT /dataSource/{dataSourceId}/access/{subscriptionId}

The /dataSource/{dataSourceId}/access/{subscriptionId} endpoint cannot be used for connection-backed data sources when updating a user to an owner. To complete this action on any connection-backed data sources, use the /data endpoint to update the dataOwners.

Change user status for a specific data source. Requestors cannot update their own status for a data source.

Required: The global GOVERNANCE permission or be the data source owner

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.com/dataSource/23/access/95

Payload example

{
  "state": "subscribed"
}

Path parameters

Attribute	Description	Required
dataSourceId	Integer The data source ID.	Yes
subscriptionId	Integer The data source member's subscription ID.	Yes

Payload parameters

Attribute	Description	Required
state	string The new status for the user: subscribed, owner, expert or ingest.	Yes

Response

Returns the updated subscription record for the data source member.

Attribute	Description
id	integer The data source member's subscription ID.
modelId	integer The model ID.
modelType	array The Immuta component the user's subscription is updated for: datasource or project.
state	array The current state of the user's role: subscribed, owner, expert, or ingest.
profile	integer The profile ID.
group	integer If a group's status is being updated, this is the group ID.
expiration	timestamp The date the user will no longer have access to the data source.
acknowledgeRequired	boolean This attribute is specific to projects. When true the user needs to confirm they have read the project acknowledgement statement.
createdAt	timestamp The date and time created.
updatedAt	timestamp The date and time updated.
originalState	array The user's previous status for the data source.
approved	boolean If true, the status is approved.

{
  "id": 95,
  "modelId": "3",
  "modelType": "datasource",
  "state": "subscribed",
  "metadata": {},
  "admin": 2,
  "profile": 3,
  "group": null,
  "expiration": null,
  "acknowledgeRequired": false,
  "createdAt": "2021-10-12T15:40:13.878Z",
  "updatedAt": "2021-10-12T16:10:46.801Z",
  "originalState": "expert",
  "approved": true
}