Book a demo

Manage Projects

Projects API reference guide

This page details how to use the projects API to query projects and the data sources associated with them in Immuta.

Projects workflow

  1. Create a project.

  2. Search for Immuta projects.

  3. Manage your Immuta projects.

  4. Manage project members.

  5. Manage project data sources.

  6. Use projects.

  7. Delete projects.

Create a project

POST /project

Create the project.

Payload parameters

Attribute
Description
Required

id

integer Project ID.

Yes

projectKey

string Name of the project.

Yes

name

string Name of the project.

Yes

status

string (Accepted statuses are open or closed.)

Yes

description

string Project description.

No

documentation

string Project documentation.

No

tags

array Project tags.

No

purposes

array Project purposes.

No

stagedPurposes

array Project purposes staged for approval.

No

deleted

boolean If true, the project will be deleted.

No

snowflake

array This enables a Snowflake workspace for the project and details the schema, hostname, and warehouse. Support for Snowflake project workspaces has been deprecated.

No

allowMaskedJoins

boolean If true, masked joins will be allowed.

No

subscriptionPolicy

array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription. If this is not set, it will be the default manual.

No

subscriptionType

string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).

No

equalization

array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.

No

workspace

array Information on workspaces in the project.

No

type

string The type of Immuta project, either user created project (user) or system generated project (schema).

No

createdAt

timestamp Date of the project creation.

No

updatedAt

timestamp Date of the most recent update.

No

Response parameters

Attribute
Description

id

integer Project ID.

projectKey

string Name of the project.

name

string Name of the project.

status

string (Statuses are open or closed.)

description

string Project description.

documentation

string Project documentation.

tags

array Project tags.

purposes

array Project purposes.

stagedPurposes

array Project purposes staged for approval.

deleted

boolean If true, the project has been deleted.

snowflake

array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.

allowMaskedJoins

boolean If true, masked joins are allowed.

subscriptionPolicy

array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.

subscriptionType

string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).

equalization

array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.

workspace

array Information on workspaces in the project.

type

string The type of Immuta project, either user created project (user) or system generated project (schema).

createdAt

timestamp Date of the project creation.

updatedAt

timestamp Date of the most recent update.

workspaceWarnings

string This message describes issues with the created workspace.

Example request

This example request with the payload below will create a new project.

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

Example request payload

This example payload will create a new project named API Project.

{
  "id": 4,
  "projectKey": "api project",
  "name": "API Project",
  "status": "open",
  "description": "project created with api",
  "deleted": false,
  "allowMaskedJoins": false,
  "createdAt": "2021-09-10",
  "updatedAt": "2021-09-10"
}

Example response

{
  "id": 4,
  "projectKey": "api project",
  "name": "API Project",
  "status": "open",
  "description": "project created with api",
  "documentation": "# API Project",
  "deleted": false,
  "allowMaskedJoins": false,
  "subscriptionType": "manual",
  "subscriptionPolicy": null,
  "equalization": null,
  "workspace": null,
  "snowflake": null,
  "type": null,
  "schema": null,
  "createdBy": 2,
  "updatedBy": 2,
  "createdAt": "2021-09-10T00:00:00.000Z",
  "updatedAt": "2021-09-10T00:00:00.000Z",
  "schemaEvolutionId": null,
  "purposes": [],
  "stagedPurposes": []
}

Search projects

Method
Path
Purpose

GET

/project

Search for projects.

GET

/project/{projectId}

Get the project with the given ID.

Search all projects

GET /project

Search for projects.

Query parameters

Attribute
Description
Required

offset

integer Used in combination with size to fetch pages. The default is 0.

No

size

integer The number of results to return per page.

No

sortField

string Used to sort results by field.

No

sortOrder

string Sorts results by order, which must be asc or desc. The default is asc.

No

subscription

array[string] Filters projects by subscription types, which must be automatic, approval, or policy.

No

status

array[string] Filters projects based on their status: open or closed.

No

searchText

string Searches text. By default, this will filter projects by name, description, documentation, category, and organization.

No

tag

array[string] Filters projects by tags associated with the projects.

No

nameOnly

boolean If true, searchText will only filter by project name, allowing you to retrieve specific projects. The default is false.

No

isEqualized

boolean If true, only equalized projects will be included.

No

snowflake

boolean If true, only projects with a Snowflake workspace will be included.

No

dataSourceId

integer Filters projects by whether they have the data source associated with the data source ID.

No

mode

integer Specifies the query mode, which must be 0 (FULL), 1 (COUNT), 4 (TAG), 5 (MIN_MAX), or 6 (STATUS).

No

Response parameters

Attribute
Description

count

integer Number of projects found.

hits

array Details about each project listed.

id

integer The project ID.

projectKey

string Name of the project.

name

string Name of the project.

status

string Statuses are open or closed.

description

string Project description.

documentation

string Project documentation.

tags

array Project tags.

purposes

array Project purposes.

stagedPurposes

array Project purposes staged for approval.

deleted

boolean If true, the project has been deleted.

snowflake

array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.

allowMaskedJoins

boolean If true, masked joins are allowed.

subscriptionPolicy

array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.

subscriptionType

string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).

equalization

array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.

workspace

array Information on workspaces in the project.

type

string The type of Immuta project, either user created project (user) or system generated project (schema).

createdAt

timestamp Date of the project creation.

updatedAt

timestamp Date of the most recent update.

acknowledgeRequired

boolean When true, the requesting user has not yet agreed to the project acknowledgement.

subscriptionId

integer The project member's subscription ID.

subscribedAsUser

boolean If true, the user running the request is currently subscribed.

subscriptionStatus

string Subscription status of the user running the request.

filterId

integer Corresponds with the ID of the project.

facets

array Facets (categories) relevant to the search.

Request example

This example request gets a list of all of the projects.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/project

Response example

{
  "hits": [
    {
      "id": 8,
      "name": "Improving Employee Onboarding and Retention",
      "status": "open",
      "description": null,
      "deleted": false,
      "updatedAt": "2021-07-14T23:14:46.210Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-07-14T23:13:53.752Z",
      "filterId": 8,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "not_subscribed",
      "purposeCount": 1,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": null,
      "allowMaskedJoins": false
    },
    {
      "id": 4,
      "name": "Medical Records",
      "status": "open",
      "description": "This project contains all data sources under the schema, medical_records, from [email protected]:1433/example.",
      "deleted": false,
      "updatedAt": "2021-06-22T23:24:58.766Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-06-22T23:24:58.766Z",
      "filterId": 4,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "owner",
      "purposeCount": 0,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": "Schema",
      "allowMaskedJoins": false
    },
    {
      "id": 6,
      "name": "sample123",
      "status": "open",
      "description": null,
      "deleted": false,
      "updatedAt": "2021-07-12T21:32:37.020Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-07-12T21:32:37.012Z",
      "filterId": 6,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "not_subscribed",
      "purposeCount": 1,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": null,
      "allowMaskedJoins": false
    },
    {
      "id": 2,
      "name": "test",
      "status": "open",
      "description": null,
      "deleted": false,
      "updatedAt": "2021-07-19T20:48:00.758Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-05-19T22:50:44.190Z",
      "filterId": 2,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "owner",
      "purposeCount": 2,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": null,
      "allowMaskedJoins": false
    },
    {
      "id": 3,
      "name": "Tpc",
      "status": "open",
      "description": "This project contains all data sources under the schema, tpc, from [email protected]:1433/example.",
      "deleted": false,
      "updatedAt": "2021-05-20T16:29:09.679Z",
      "subscriptionPolicy": null,
      "createdAt": "2021-05-20T16:29:09.679Z",
      "filterId": 3,
      "subscriptionType": "manual",
      "isEqualized": false,
      "acknowledgeRequired": false,
      "subscriptionStatus": "owner",
      "purposeCount": 0,
      "hasDeletedPurposes": false,
      "workspace": null,
      "type": "Schema",
      "allowMaskedJoins": false
    }
  ],
  "facets": {},
  "count": 5
}

Search for projects by ID

GET /project/{projectId}

Get the project with the given ID.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

checkForSqlAccount

boolean Default is true.

No

Response parameters

Attribute
Description

id

integer Project ID.

projectKey

string Name of the project.

name

string Name of the project.

status

string Statuses are open or closed.

description

string Project description.

documentation

string Project documentation.

tags

array Project tags.

purposes

array Project purposes.

stagedPurposes

array Project purposes staged for approval.

deleted

boolean If true, the project has been deleted.

snowflake

array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.

allowMaskedJoins

boolean If true, masked joins are allowed.

subscriptionPolicy

array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.

subscriptionType

string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).

equalization

array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.

workspace

array Information on workspaces in the project.

type

string The type of Immuta project, either user created project (user) or system generated project (schema).

createdAt

timestamp Date of the project creation.

updatedAt

timestamp Date of the most recent update.

acknowledgeRequired

boolean When true, the requesting user has not yet agreed to the project acknowledgement.

subscriptionId

integer The project member's subscription ID.

subscribedAsUser

boolean If true, the user running the request is currently subscribed.

subscriptionStatus

string Subscription status of the user running the request.

Example request

This example gets the project object for the project with the ID 2.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/project/2

Example response

{
  "id": 2,
  "projectKey": "test",
  "name": "test",
  "status": "open",
  "description": null,
  "documentation": "# test\n\n12345",
  "deleted": true,
  "allowMaskedJoins": true,
  "subscriptionType": "manual",
  "subscriptionPolicy": null,
  "equalization": null,
  "workspace": null,
  "snowflake": null,
  "type": null,
  "schema": null,
  "createdBy": 2,
  "updatedBy": 2,
  "createdAt": "2021-05-19T22:50:44.190Z",
  "updatedAt": "2021-07-29T18:30:04.066Z",
  "schemaEvolutionId": null,
  "subscribedAsUser": true,
  "subscriptionId": 5,
  "acknowledgeRequired": false,
  "subscriptionStatus": "owner",
  "requestedState": "owner",
  "approved": true,
  "subscriptionExpiration": null,
  "filterId": 2,
  "purposeCount": null,
  "purposes": [
    {
      "id": 8,
      "name": "Analyzing Onboarding and Job Satisfaction",
      "acknowledgement": null,
      "description": "Data can only be accessed for analyzing the effectiveness of current onboarding practices and trends in employee job satisfaction  reasons for data access must be approved by a compliance committee.",
      "addedByProfile": 2,
      "displayAcknowledgement": true,
      "deleted": false,
      "systemGenerated": false,
      "createdAt": "2021-07-07T19:56:06.360Z",
      "updatedAt": "2021-07-07T19:56:06.360Z",
      "createdBy": 2
    },
    {
      "id": 4,
      "name": "Use Case Outside De-identification",
      "acknowledgement": "I agree to use the data associated with this project for the stated purpose of the project, and for that purpose only, as listed in the project's homepage, and to refrain from sharing that data outside of the project or Immuta. In the event that I discover risks that I believe could lead to unauthorized access, I agree to immediately notify the project owner or governance team and take immediate action t  address and mitigate such risks.",
      "description": null,
      "addedByProfile": 1,
      "displayAcknowledgement": true,
      "deleted": false,
      "systemGenerated": true,
      "createdAt": "2021-05-19T20:32:03.437Z",
      "updatedAt": "2021-07-28T14:17:22.690Z",
      "createdBy": 2
    }
  ],
  "stagedPurposes": [],
  "tags": []
}

Manage projects

Method
Path
Purpose

PUT

/project/{projectId}

Update the project with the given ID.

GET

/project/{projectId}/activity

Get all of the recent activity for a given project.

GET

/project/{projectId}/checkEqualizationState

Get current state of an equalized project.

Update project by ID

PUT /project/{projectId}

Update the project with the given ID.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

deleteDataSources

boolean If true, the data sources in the project will be deleted.

No

Payload parameters

Attribute
Description
Required

type

string The type of Immuta project, either user created project (user) or system generated project (schema).

No

name

string The project's new name.

No

description

string The project's new description.

No

documentation

string The project's new documentation.

No

status

string Accepted statuses are open or closed.

No

subscriptionType

string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).

No

tags

array The project's new tags.

No

purposes

array The project's new purposes.

No

stagedPurposes

array The project's new purposes staged for approval.

No

deleted

boolean If true, the project will be deleted.

No

snowflake

array This enables a Snowflake workspace for the project and details the schema, hostname, and warehouse.

No

allowMaskedJoins

boolean If true, masked joins will be allowed.

No

subscriptionPolicy

array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription. If this is not set, it will be the default manual.

No

equalization

array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.

No

workspace

array Information on workspaces in the project.

No

Response parameters

Attribute
Description

id

integer Project ID.

projectKey

string Name of the project.

name

string Name of the project.

status

string Statuses are open or closed.

description

string Project description.

documentation

string Project documentation.

tags

array Project tags.

purposes

array Project purposes.

stagedPurposes

array Project purposes staged for approval.

deleted

boolean If true, the project will be deleted.

snowflake

array If a Snowflake workspace has been enabled for the project, this attribute will detail the schema, hostname, and warehouse.

allowMaskedJoins

boolean If true, masked joins will be allowed.

subscriptionPolicy

array[object] A policy object for the Subscription Policy on the project. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.

subscriptionType

string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).

equalization

array Details the policy conditions of the equalization, including the configured (or recommended) user groups and attributes.

workspace

array Information on workspaces in the project.

type

string The type of Immuta project, either user created project (user) or system generated project (schema).

createdAt

timestamp Date of the project creation.

updatedAt

timestamp Date of the most recent update.

workspaceWarnings

string This message describes issues with the created workspace.

Example request

This example request with the payload below will update the project with the project ID 2.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/2

Example request payload

This example payload will update the project to be named Documentation Project.

{
  "name": "Documentation Project",
  "deleted": false
}

Example response

{
  "workspace": null,
  "createdBy": 2,
  "updatedBy": 2,
  "schemaEvolutionId": 1,
  "projectKey": "Medical Records",
  "name": "Documentation Project",
  "status": "open",
  "description": "This project contains all data sources under the schema, medical_records, from [email protected]:1433/example.",
  "documentation": "This is an automatically generated project that collects data sources under the schema, medical_records, from [email protected]:1433/example. When data sources in this schema are added to the system, they will automatically be added to this project.",
  "deleted": false,
  "allowMaskedJoins": false,
  "subscriptionType": "manual",
  "subscriptionPolicy": null,
  "equalization": null,
  "snowflake": null,
  "type": "Schema",
  "schema": "medical_records",
  "id": 2,
  "createdAt": "2021-08-24T15:44:29.477Z",
  "updatedAt": "2021-09-10T21:49:00.678Z",
  "purposeCount": 0,
  "tags": [],
  "projectPurposes": [],
  "stagedPurposes": [],
  "purposes": [],
  "workspaceWarnings": []
}

View project activity by project ID

GET /project/{projectId}/activity

Get all of the recent activity for a given project.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

offset

integer Used in combination with size to fetch pages.

No

size

integer Used to select the number of activities.

No

Response parameters

Attribute
Description

count

integer The total number of actions.

activities

array The id, modelType, modelId, notificationType, actionsBy, targetUser, targetGroup, additionalText, array, createdAt, updatedAt, and read for each action listed.

id

integer The activity ID.

modelType

string The Immuta feature the activity is attached to.

modelId

string The ID of the Immuta feature the activity is attached to.

notificationType

string The type of activity or notification, such as modelCreated, modelUserAdded, or projectUpdated.

actionBy

array The user data for the user who took the action.

targetUser

array The user data for the user who the action was directed towards.

targetGroup

array The group data for the group who the action was directed towards.

metadata

array Details about the action. For example, if the notificationType was modelCreated, the metadata attribute would include the project name.

createdAt

timestamp Date the action was taken.

updatedAt

timestamp Date of the most recent activity on the action.

read

boolean If true, the activity has been viewed.

unread

integer The number of unviewed activities on that project.

Example request

This example gets one activity for the project with the project ID 2.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/2/activity?size=1

Example response

{
  "count": 40,
  "activities": [
    {
      "modelType": "project",
      "modelId": "2",
      "createdAt": "2021-07-29T20:56:11.856Z",
      "notificationType": "projectUpdated",
      "metadata": {
        "fields": [
          "deleted",
          "purposes"
        ],
        "projectName": "test",
        "approvedPurposeCount": 0,
        "deniedPurposesCount": 0,
        "requestedPurposeCount": 0,
        "newPurposesAddedCount": 2
      },
      "read": false,
      "id": 191,
      "updatedAt": "2021-07-29T20:56:11.856Z",
      "actionBy": {
        "id": 2,
        "name": "John Doe",
        "email": "[email protected]"
      },
      "targetUser": {
        "id": 2,
        "name": "John Doe",
        "email": "[email protected]"
      }
    }
  ],
  "unread": 40,
  "next": "191_2021-07-29T20:56:11.856Z"
}

View the state of an equalized project

GET /project/{projectId}/checkEqualizationState

Get current state of an equalized project.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

Response parameters

Attribute
Description

equalizationState

string The state of the project's equalization. Options include: off, recommended, active, upgrade, or nonCompliantMembers.

Example request

This example gets the state of project equalization of the project with the project ID 2.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/2/checkEqualizationState

Example response

{
  "equalizationState": "recommended"
}

Manage project members

Method
Path
Purpose

GET

/project/{projectId}/members

Get all of the members for a given project.

POST

/project/{projectId}/checkEqualizedAuths

Check that all members meet the provided equalized entitlements.

POST

/project/{projectId}/members

Add a member to the project.

PUT

/project/{projectId}/members/{subscriptionId}

Update a member of the project.

View project members

GET /project/{projectId}/members

Get all of the members for a given project.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

offset

integer Used in combination with size to fetch pages.

No

size

integer The number of results to return per page.

No

sortField

string Sorts results by field. The default is name.

No

sortOrder

string Sorts results by order, which must be asc or desc. The default is asc.

No

searchText

string Searches text of member names.

No

approved

boolean Filters results based on whether or not members' subscription status has been approved.

No

checkDataSources

boolean When true, will check if users' meet the compliance requirements set on data sources within the project.

No

expandGroups

boolean

No

Response parameters

Attribute
Description

count

integer The number of members in the project.

members

array The profile, name, iamId, userId, email, type, approved, state, systemGenerated, lastExternalRefresh, subscriptionId, createdAt, updatedAt, approvals, currentUserCanApprove, and compliance for each member result.

profile

integer The user's profile ID.

name

string The user's name.

iamId

string The ID of the IAM, which is configured on the App Settings page.

userId

string The user's Immuta username.

email

string The user's email.

type

string The type of Immuta project, either user created project (user) or system generated project (schema).

approved

boolean When true, the members' subscription status has been approved.

state

string The user's relationship to the project. Options include owner, not_subscribed, pending, subscribed, and expert.

systemGenerated

boolean When true, the user is a system generated account.

lastExternalRefresh

timestamp The date of the last time this user's information was updated from an external IAM.

subscriptionId

integer The project member's subscription ID.

createdAt

timestamp The date that this user was created in Immuta.

updatedAt

timestamp The date of the most recent update of the user.

approvals

array Details on how this new member will fit into the project's approval process.

compliance

array Details about the compliance requirements of the project, including missingDataSources and invalidSubscriptions.

Example request

This request gets all of the members of the project with the project ID 2.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/2/members

Example response

{
  "count": 1,
  "members": [
    {
      "profile": 2,
      "name": "John Doe",
      "iamid": "bim",
      "userid": "[email protected]",
      "email": "[email protected]",
      "type": "user",
      "approved": true,
      "state": "owner",
      "systemGenerated": false,
      "lastExternalRefresh": "2021-07-30T17:49:55.050Z",
      "subscriptionId": 5,
      "createdAt": "2021-05-19T22:50:44.206Z",
      "updatedAt": "2021-07-19T20:47:53.069Z",
      "approvals": [],
      "currentUserCanApprove": false
    }
  ]
}

Check the members' equalized entitlements

POST /project/{projectId}/checkEqualizedAuths

Check that all members meet the provided equalized entitlements.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

Payload parameters

Attribute
Description
Required

conditionsObj

array Details containing operator, conditions, type, group, and field values.

Yes

operator

string

Yes

conditions

array Details containing type, group, and field.

Yes

type

string The type of Immuta project, either user created project (user) or system generated project (schema).

No

group

array Includes the group id, name, and iam.

No

Response parameters

Attribute
Description

validSet

boolean When true, users meet the specified entitlements.

usersMissingAuths

array Metadata about the user (name and subscription id) and the name of the group they're missing.

Request example

This request with the payload below will check if the requesting user is in the "View Masked Values" group.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/1/checkEqualizedAuths

Payload example

{
  "conditionsObj": {
    "operator": "and",
    "conditions": [
      {
        "type": "groups",
        "group": {
          "id": 1,
          "name": "View Masked Values"
        }
      }
    ]
  }
}

Response example

{
  "validSet": true,
  "usersMissingAuths": {}
}

Add a member to a project

POST /project/{projectId}/members

Add a member to the project.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

Payload parameters

Attribute
Description
Required

profileId

integer The new user's ID.

Yes

groupId

integer The group ID that the new user is a part of. This will add a whole group.

No

state

string The new user's connection to the project. Options include owner, not_subscribed, pending, subscribed, and expert.

No

expiration

timestamp The date when the member should no longer have access to the project.

No

approvals

array Details on how this new member will fit into the project's approval process.

No

Example request

This example request with the payload below will add a new member to the project with the project ID 1.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https:demo.immuta.com/project/1/members

Example request payload

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

Example response

{
  "subscriptionId": 18,
  "state": "subscribed",
  "approved": true
}

Update a project member

PUT /project/{projectId}/members/{subscriptionId}

Update a member of the project.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

subscriptionId

integer The project member's subscription ID.

Yes

Payload parameters

Attribute
Description
Required

state

array[string] The user's role in the project. Options include owner, not_subscribed, pending, subscribed, and expert.

Yes

expiration

timestamp The date when the member should no longer have access to the project.

No

Response parameters

Attribute
Description

state

array[string] The user's role in the project. Options include owner, not_subscribed, pending, subscribed, and expert.

expiration

timestamp The date when the member should no longer have access to the project.

Request example

This example request with the payload below will update the user with the subscription ID 2 to be a subscriber of the project with the project ID 3.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/3/members/2

Payload example

{
  "state": "subscribed"
}

Response example

{
  "state": "subscribed",
  "expiration": null
}

Manage project data sources

Method
Path
Purpose

GET

/project/{projectId}/dataSources

Get all of the data sources for a given project.

DELETE

/project/{projectId}/dataSources

Remove supplied data sources from the project.

POST

/project/{projectId}/dataSources

Add data sources to a project.

PUT

/project/{projectId}/dataSources/{dataSourceId}

Update the reason for adding a data source to a project.

View project data sources by project ID

GET project/{projectId}/dataSources

Get all of the data sources for a given project.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

offset

integer Used in combination with size to fetch pages.

No

searchText

string Searches text of the data source names.

No

size

integer The number of results to return per page.

No

sortField

string Used to sort results by field. Options include addedBy, addedOn, and dataSourceName. The default is dataSourceName.

No

sortOrder

string Sorts results by order, which must be asc or desc. The default is asc.

No

unsubscribed

boolean If true, filters by unsubscribed status (includes data sources with a pending subscription). If false, filters by subscribed status.

No

subscription

string Searches based on the subscription status of the user. Options include not_subscribed, owner, pending, or subscribed.

No

Response parameters

Attribute
Description

count

integer The total number of data sources in the project.

dataSources

array[object] An array of data source objects that includes addedBy, dataSourceName, policyHandlerType, addedOn, dataSourceId, addedByProfile, deleted, subscriptionType, subscriptionStatus, subscriptionPolicy, connectionString, blobHandlerType, and derivedThisProject values for each data source.

addedBy

string The user who added the data source to the project.

dataSourceName

string The name of the data source.

policyHandlerType

string

addedOn

timestamp The date the data source was added to the project.

dataSourceId

integer The data source ID.

addedByProfile

integer The profile ID of the user who added the data source to the project.

deleted

boolean If true, the data source has been deleted.

subscriptionType

string The type of subscription policy on the project. The type can be automatic (which allows anyone to subscribe), approval (which requires the subscriber to be manually approved), policy (which only allows users with specific groups or attributes to subscribe), or manual (which requires users to be manually added).

subscriptionStatus

string

subscriptionPolicy

array[object] A policy object for the Subscription Policy on the data source. Details include type, exceptions, conditions, allowDiscovery, and automaticSubscription.

connectionString

string The data source connection string.

blobHandlerType

string The data platform.

derivedInThisProject

boolean If true, this data source was created as a derived data source in this project.

Example request

This example gets the data source details for all of the data sources of the project with the project ID 2.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/2/dataSources

Example response

{
  "count": 3,
  "dataSources": [
    {
      "addedBy": "John Doe",
      "dataSourceName": "Fake Medical Claims 2017",
      "policyHandlerType": "Builder",
      "addedOn": "2021-06-25T19:11:03.230Z",
      "dataSourceId": 8,
      "addedByProfile": 2,
      "deleted": false,
      "subscriptionType": "policy",
      "subscriptionStatus": "owner",
      "subscriptionPolicy": {
        "type": "subscription",
        "exceptions": {
          "operator": "or",
          "conditions": [
            {
              "type": "groups",
              "group": {
                "name": "HR Department"
              }
            },
            {
              "type": "authorizations",
              "authorization": {
                "auth": "Manager",
                "value": "Receiving Surveys"
              }
            }
          ]
        },
        "shareResponsibility": false,
        "automaticSubscription": true
      },
      "connectionString": "[email protected]:1433/example",
      "blobHandlerType": "Snowflake",
      "derivedInThisProject": false
    },
    {
      "addedBy": "John Doe",
      "dataSourceName": "Tpc Randomized",
      "policyHandlerType": "Builder",
      "addedOn": "2021-06-25T22:26:38.170Z",
      "dataSourceId": 6,
      "addedByProfile": 2,
      "deleted": false,
      "subscriptionType": "policy",
      "subscriptionStatus": "owner",
      "subscriptionPolicy": {
        "type": "subscription",
        "exceptions": {
          "operator": "and",
          "conditions": [
            {
              "type": "groups",
              "group": {
                "name": "HR"
              }
            }
          ]
        },
        "shareResponsibility": false,
        "automaticSubscription": true
      },
      "connectionString": "[email protected]:1433/example",
      "blobHandlerType": "Azure Synapse Analytics",
      "derivedInThisProject": false
    },
    {
      "addedBy": "John Doe",
      "dataSourceName": "Tpc Web Sales",
      "policyHandlerType": "None",
      "addedOn": "2021-06-25T19:11:03.226Z",
      "dataSourceId": 7,
      "addedByProfile": 2,
      "deleted": false,
      "subscriptionType": "manual",
      "subscriptionStatus": "owner",
      "subscriptionPolicy": null,
      "connectionString": "[email protected]:1433/example",
      "blobHandlerType": "Azure Synapse Analytics",
      "derivedInThisProject": false
    }
  ]
}

Remove data sources from a project

DELETE /project/{projectId}/dataSources

Remove supplied data sources from the project.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

ids

integer The IDs of the data sources to remove from the project.

Yes

Response parameters

Attribute
Description

success

array The id, blobHandlerType, and name values of the data sources that have been successfully removed.

inError

array The id, blobHandlerType, and name values of the data sources that have not been successfully removed.

id

integer The data source ID.

blobHandlerType

string The type of blob handler of the data source.

name

string The data source name.

Example request

This example request deletes the data source with the ID 8 from the project with the project ID 2.

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/2/dataSources?ids=8

Example response

{
  "success": [
    {
      "id": 8,
      "name": "Fake Medical Claims 2017",
      "blobHandlerType": "Snowflake"
    }
  ],
  "inError": []
}

Add data sources to a project

POST /project/{projectId}/dataSources

Adds data sources to a project.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

Payload parameters

Attribute
Description
Required

dataSourceIds

integer The data source IDs for the data sources to add to the project.

Yes

Response parameters

Attribute
Description

success

array The id, blobHandlerType, and name values of the data sources that have been successfully added.

inError

array The id, blobHandlerType, and name values of the data sources that have not been successfully added.

id

integer The data source ID.

blobHandlerType

string The type of blob handler of the data source.

name

string The data source name.

Example request

This example request with the payload below will add the data source with the data source ID 1 to the project with the project ID 1.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/1/dataSources

Example request payload

This example payload will add the data source with the data source ID 2 to the project.

{
  "dataSourceIds": [
    2
  ]
}

Example response

{
  "success": [
    {
      "id": 2,
      "name": "Credit Payments Bank Deposits",
      "blobHandlerType": "Snowflake"
    }
  ],
  "inError": []
}

Update the reason for adding a data source

PUT /project/{projectId}/dataSources/{dataSourceId}

Updates the reason for adding a data source to a project.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

dataSourceId

integer The data source ID.

Yes

Request example

This example request with the payload below will update the reason that the data source with the data source ID 1 was added to the project with the project ID 1.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/1/dataSources/1

Response example

None.

Use projects

Method
Path
Purpose

DELETE

/project/{projectId}/unsubscribe

Unsubscribe from a project.

POST

/project/current/{projectId}

Set the current project ID the current user is acting under.

POST

/project/current/null

Set current project to None.

POST

/project/{projectId}/members/{subscriptionId}/acknowledge

Acknowledge all the restrictions on this project.

Unsubscribe from a project

DELETE /project/{projectId}/unsubscribe

Unsubscribe from a project.

Query parameters

Attribute
Description
Required

projectId

string The project ID.

Yes

Request example

This example request unsubscribes the user from the project with the project ID 5.

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/5/unsubscribe

Select the current project to act under

POST /project/current/{projectId}

Set the current project ID the current user is acting under.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

Request example

This example request sets the current project to act under as the project with the project ID 1.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/current/1

Set current project to None

POST /project/current/null

Set the project context to None.

Request example

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/current/null

Acknowledge the project restrictions

POST /project/{projectId}/members/{subscriptionId}/acknowledge

Acknowledge all the restrictions on this project.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

subscriptionId

integer The project member's subscription ID.

Yes

Payload parameters

Attribute
Description
Required

text

string

Yes

Response parameters

Attribute
Description

acknowledgeRequired

boolean When true, the requesting user has not yet agreed to the project acknowledgement.

purposes

array Details of the purpose that has been acknowledged.

Request example

This example request acknowledges all of the purposes in the project with the project ID 1.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/project/1/members/1/acknowledge

Payload example

{}

Response example

{
  "acknowledgeRequired": false,
  "purposes": [
    {
      "id": 1,
      "name": "Re-identification Prohibited",
      "acknowledgement": "I agree to use the data associated with this project for the stated purpose of the project, and for that purpose only, as listed in the project's homepage, and to refrain from sharing that data outside of the project or Immuta. I also agree not to re-identify or take any steps to re-identify the individuals whose personal information is contained in the data sources attached to the project. In the event that these individuals have been identified or that I discover risks that I believe could lead to their identification, I agree to immediately notify the project owner or governance team and take immediate action to address and mitigate such risks. I further agree to refrain from contacting any individuals who might be identified."
    }
  ]
}

Delete project by ID

DELETE /project/{projectId}

Delete the project with the given ID.

Query parameters

Attribute
Description
Required

projectId

integer The project ID.

Yes

Response parameters

Attribute
Description

hardDelete

boolean If true, the project was permanently deleted.

Example request

This example request will delete the project with the project ID 4.

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/project/4

Example response

{
  "hardDelete": true
}
PreviousManage Projects and PurposesNextManage Purposes

Last updated

Was this helpful?