1 of 10

Configure Immuta

This section of API documentation is specific to configuring elements of your instance, such as users, tags, licenses, integrations, and webhooks.

Section Contents

Activities and notifications: View your activity notifications.
Fingerprint service status: Check the status of the Fingerprint service.
IAMs: Manage users and their permissions, groups, and attributes.
Licenses: Manage and view licenses in Immuta.
Search filters
Sensitive data discovery: Configure custom sensitive data discovery rules and tags.
Tags: Create and search for tags.
Webhooks: Create webhooks that are triggered by events that happen in the system.

Activities and Notifications

This page describes the activity endpoint of the Immuta API, which allows you to view your activity notifications.

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

Review your notifications

Method

Path

Purpose

Review your activity notifications

GET /activity

View your activity notification feed.

Query parameters

Attribute

Description

Required

Response parameters

Request example

This example request gets 5 activities for the current user and sorts them in descending order.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/activity?size=5&sortOrder=desc

Response example

{
  "count": 210,
  "activities": [
    {
      "modelType": "datasource",
      "modelId": "105",
      "createdAt": "2021-05-04T18:39:08.712Z",
      "notificationType": "modelUserDeleted",
      "metadata": {
        "dataSourceName": "Public Uciml Census Income Enriched",
        "activity": "access",
        "action": "revoked"
      },
      "read": false,
      "id": 1255,
      "updatedAt": "2021-05-04T18:39:08.712Z",
      "actionBy": {
        "id": 2,
        "name": "John",
        "email": "john.doe@immuta.com"
      },
      "targetUser": {
        "id": 2,
        "name": "John",
        "email": "john.doe@immuta.com"
      }
    },
    {
      "modelType": "datasource",
      "modelId": "106",
      "createdAt": "2021-05-04T18:39:08.696Z",
      "notificationType": "modelUserDeleted",
      "metadata": {
        "dataSourceName": "Public Fake Medical Claims 2017",
        "activity": "access",
        "action": "revoked"
      },
      "read": false,
      "id": 1254,
      "updatedAt": "2021-05-04T18:39:08.696Z",
      "actionBy": {
        "id": 2,
        "name": "John",
        "email": "john.doe@immuta.com"
      },
      "targetUser": {
        "id": 2,
        "name": "John",
        "email": "john.doe@immuta.com"
      }
    },
    {
      "modelType": "datasource",
      "modelId": "105",
      "createdAt": "2021-05-04T18:39:08.649Z",
      "notificationType": "modelDeleted",
      "metadata": {
        "dataSourceName": "Public Uciml Census Income Enriched",
        "fields": {
        "deleted": true
      }
    },
      "read": false,
      "id": 1253,
      "updatedAt": "2021-05-04T18:39:08.649Z",
      "actionBy": {
        "id": 2,
        "name": "John",
        "email": "john.doe@immuta.com"
      },
      "targetUser": {
        "id": 2,
        "name": "John",
        "email": "john.doe@immuta.com"
      }
    },
    {
      "modelType": "datasource",
      "modelId": "106",
      "createdAt": "2021-05-04T18:39:08.650Z",
      "notificationType": "modelDeleted",
      "metadata": {
        "dataSourceName": "Public Fake Medical Claims 2017",
        "fields": {
        "deleted": true
      }
    },
      "read": false,
      "id": 1252,
      "updatedAt": "2021-05-04T18:39:08.650Z",
      "actionBy": {
        "id": 2,
        "name": "John",
        "email": "john.doe@immuta.com"
      },
      "targetUser": {
        "id": 2,
        "name": "John",
        "email": "john.doe@immuta.com"
      }
    },
    {
      "modelType": "datasource",
      "modelId": "103",
      "createdAt": "2021-05-04T18:39:08.555Z",
      "notificationType": "modelUserDeleted",
      "metadata": {
        "dataSourceName": "Public Credit Transactions",
        "activity": "access",
        "action": "revoked"
      },
      "read": false,
      "id": 1251,
      "updatedAt": "2021-05-04T18:39:08.555Z",
      "actionBy": {
        "id": 2,
        "name": "John",
        "email": "john.doe@immuta.com"
      },
     "targetUser": {
        "id": 2,
        "name": "John",
        "email": "john.doe@immuta.com"
      }
    }
  ],
  "unread": 210,
  "next": "1251_2021-05-04T18:39:08.555Z"
}

Review your unread notifications

GET /activity/hasUnread

Determine whether you have unread activity notifications.

Response parameters

Request example

This request determines whether or not the requesting user has unread activities.

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

Response example

{
  "unread": false
}

Fingerprint Service Status

This page illustrates how to check the status of the Fingerprint service using the fingerprint endpoint.

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

Get the status of the fingerprint service

GET /fingerprint/status

Get the status of the Fingerprint service.

Response parameters

Attribute

Description

Request example

The following request gets the status of the Fingerprint service.

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

Response example

{
  "healthy": true
}

Licenses

This page outlines the admin endpoint, which allows you to manage and review licenses in Immuta.

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

Admin workflow

Add an Immuta license key to increase the number of seats or enable features.
View a list of license keys.
View the status of license seat capacity and features.
View license usage.
Delete a license key.

Add an Immuta license key

POST /admin/license

Add a license key to the Immuta tenant to increase the number of seats or enable features.

Query parameters

Parameter

Description

Required

Response schema

Attribute

Description

Request example

This example request adds a license key (saved in the example-payload.json file) to the Immuta tenant.

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

Request payload example

{
  "licensekey": "licensekey0123456789abcdefghijklstring"
}

Response example

{
  "id": 1,
  "licenseKey": "licensekey0123456789abcdefghijklstring",
  "seats": 20,
  "softSeats": 0,
  "expires": "2022-09-09T00:00:00.000Z",
  "uuid": "4ceaf808-the-u-u--id4a753fc5a",
  "deleted": false,
  "invalidated": false,
  "features": {
    "FPE": {
      "enabled": true
    }
  },
  "handlers": {},
  "hardExpiration": false,
  "renewalToken": null,
  "notice": null,
  "noticeOnExpire": null,
  "classifyUsername": null,
  "classifyToken": null,
  "createdAt": "2021-09-09T13:47:02.473Z",
  "updatedAt": "2021-10-07T17:55:54.806Z",
  "expired": false
}

View license keys

Get a list of license keys

GET /admin/license

Get a list of all license keys.

Response schema

Request example

This example request gets the license key for the https://www.organization.immuta.com Immuta tenant.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://www.organization.immuta.com/admin/license

Response example

[
  {
    "id": 1,
    "uuid": "4cthe808-uniq-uec9-univ-ersal753fcid",
    "features": {
      "FPE": {
        "enabled": true
      }
    },
    "handlers": {},
    "expires": "2022-09-09T00:00:00.000Z",
    "seats": 20,
    "createdAt": "2021-09-09T13:47:02.473Z",
    "notice": null,
    "noticeOnExpire": null
  }
]

Get the status of a license

GET /admin/license/licenseStatus

Get the status of a license key's features and seat capacity.

Response schema

Request example

This example request gets the number of seats and active users for the license key associated with the https://www.organization.immuta.com Immuta tenant.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://www.organization.immuta.com/admin/license/licenseStatus

Response example

{
  "activeUserCount": 1,
  "licenseSeats": 20,
  "canAddUser": true,
  "hardSeats": 20
}

Get license usage

GET /admin/license/usage

Get the license usage summary. This endpoint returns a summary of the number of active and inactive users and a list of users.

Query parameters

Response schema

Request example

This request gets the license usage for 5 users in the https://www.organization.immuta.com Immuta tenant.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://www.organization.immuta.com/admin/license/usage?offset=0&size=5

Response example

{
  "summary": {
    "dataConsumers": {
      "totalCount": 25,
      "activeCount": 10,
      "inactiveCount": 25
    },
    "policyOwners": {
      "totalCount": 1
    }
  },
  "users": [{
      "userType": "policyOwner",
      "name": "Kris",
      "email": "kris@example.com",
      "userid": "kris@example.com",
      "iamid": "bim"
    },
    {
      "userType": "dataConsumer",
      "active": true,
      "name": "Taylor",
      "email": "taylor@example.com",
      "userid": "taylor@example.com",
      "iamid": "AzureOIDC"
    },
    {
      "userType": "dataConsumer",
      "active": true,
      "name": "Deepu",
      "email": "deepu@example.com",
      "userid": "deepu@example.com",
      "iamid": "AzureSAML"
    },
    {
      "userType": "dataConsumer",
      "active": false,
      "name": "Marc",
      "email": "marc@example.com",
      "userid": "marc@example.com",
      "iamid": "OIDC"
    },
    {
      "userType": "dataConsumer",
      "active": true,
      "name": "Mandeep",
      "email": "mandeep@example.com",
      "userid": "mandeep@example.com",
      "iamid": "SAML"
    }
  ]
}

Delete a license key

DELETE /admin/license/{licenseId}

Delete the specified license key.

Query parameters

Response schema

Request example

This example request deletes the license key with the ID 1.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://www.organization.immuta.com/admin/license/1

Response example

{
  "id": 1,
  "licenseKey": "<your-license-key>",
  "seats": 20,
  "softSeats": 0,
  "expires": "2022-09-09T00:00:00.000Z",
  "uuid": "4cthe808-uniq-uec9-univ-ersal753fcid",
  "deleted": true,
  "invalidated": false,
  "features": {
    "FPE": {
      "enabled": true
    }
  },
  "handlers": {},
  "hardExpiration": false,
  "notice": null,
  "noticeOnExpire": null,
  "createdAt": "2021-09-09T13:47:02.473Z",
  "updatedAt": "2021-09-13T16:53:39.280Z",
  "hardDelete": false,
  "expired": false
}

Jobs

This page describes the jobs endpoint.

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

Get job status and output

POST /jobs/statuses

Get the status and output of the provided jobs.

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

The following request checks the status of the job specified in the payload.

Payload example

Response example

Search Filters

This page describes the searchFilter endpoint.

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

Save a new search filter

POST /searchFilter

Save a new search filter.

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

The following request saves a new search filter.

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

Payload example

{
  "name": "Medical Claims",
  "filter": {
    "searchText": "",
    "column": ["income_greater_than_50k"],
    "type": "datasource",
    "tag": ["Discovered.Entity.Medicare Number"]
  }
}

Response example

{
  "name": "Medical Claims",
  "filter": {
    "searchText": "",
    "column": ["income_greater_than_50k"],
    "type": "datasource",
    "tag": ["Discovered.Entity.Medicare Number"]
  }
}

Search saved search filters

GET /searchFilter

Retrieve saved search filters.

Query parameters

Response parameters

Request example

The following request retrieves all saved search filters.

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

Response example

{
  "values": [{
    "name": "States",
    "filter": {
      "type": "datasource",
      "column": ["state"],
      "searchText": ""
    }
  }]
}

Delete a search filter

DELETE /searchFilter/{searchFilterName}

Delete a search filter by name.

Query parameters

Response parameters

Request example

The following request deletes the Medical Claims search filter.

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.com/searchFilter/Medical%20Claims

Response example

{
  "name": "Medical Claims",
  "filter": {
    "tag": ["Discovered.Entity.Medicare Number"],
    "type": "datasource",
    "column": ["income_greater_than_50k"],
    "searchText": ""
  }
}

Webhooks

Webhooks notify users or other systems when actions happen in Immuta. Every action that generates a notification is available as a webhook.

This page lists the REST endpoints for managing webhooks and provides examples of requests.

Webhook overview

Application Admins can configure webhooks that are triggered by events that happen in the system (such as when data sources or projects are created), but any user can configure webhooks that are triggered by access requests and activity notifications.

All user-configured webhook integrations must respond within 10 seconds of receiving the webhook request payload. If the webhook integration takes longer to respond, the .

Webhook workflow

Create a webhook

POST /webhooks

Create a new webhook. Users can create multiple webhooks in a single request.

Webhook Notifications

Payload parameters

Response schema

Request example

The following request with the payload below creates a new webhook.

Payload example

Response example

Retrieve webhook information

Search for webhooks

GET /webhooks

Return a list of webhooks the user can see. (Admins can see all webhooks; users can only see their own webhooks.)

Response schema

Request example

The following request returns a list of webhooks the user can see.

Response example

Search for notification actions

GET /webhooks/actions

Return a list of valid notification actions that a webhook can be triggered by. |

Response schema

Request example

The following request returns a list of valid notification actions that a webhook can be triggered by.

Response example

Search for webhook records

GET /webhooks/history

Return historical records for webhook requests, including requests and responses.

Query parameters

Response schema

Request example

The following request returns historical records for webhook requests, including requests and responses.

Response example

Search for webhook by ID

GET /webhooks/{id}

Return specified webhook by ID.

Query parameters

Response schema

Request example

The following request returns details on the webhook with the ID 1.

Response example

Retry webhook by ID

POST /webhooks/history/retry/{id}

Retry webhook requests by history ID. This can be done against any history record, regardless of failure or success.

Query parameters

Response schema

Request example

The following request retries the webhook with the ID 1.

Response example

Delete a webhook

DELETE /webhooks/{id}

Delete a webhook by ID.

Query parameters

Response schema

Request example

The following request deletes the webhook with the ID 1.

Response example

Troubleshooting

Timed out request

Request example

Response example

IAMs

This page details the bim API, which allows users to programmatically access information about users, their group memberships, and authentications. Most of the actions described here require ADMIN permissions.

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

BIM workflow

Because the BIM endpoint encompasses groups, users, and authentications, there are three workflows.

Create a new user

POST /bim/iam/bim/user

Create a new BIM user.

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request with the payload below will create a new BIM user with the username charlie.doe@immuta.com.

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

Payload example

{
  "iamid": "bim",
  "userid": "charlie.doe@immuta.com",
  "profile": {
    "name": "Charlie Doe",
    "email": "charlie.doe@immuta.com"
  },
  "permissions": []
}

Response example

{
  "newUser": {
    "id": 18,
    "iamid": "bim",
    "userid": "charlie.doe@immuta.com",
    "bimAuthorizations": null,
    "iamAuthorizations": null,
    "authorizations": {},
    "permissions": ["CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT"],
    "profile": {
      "name": "Charlie Doe",
      "email": "charlie.doe@immuta.com",
      "phone": null,
      "about": null,
      "location": null,
      "organization": null,
      "position": null,
      "preferences": null,
      "externalUserIds": {},
      "scim": null,
      "systemGenerated": false,
      "id": 18,
      "createdAt": "2021-10-07T01:35:13.382Z",
      "updatedAt": "2021-10-07T01:35:13.382Z"
    },
    "authentication": null,
    "systemGenerated": false,
    "lastLogin": null,
    "lastExternalRefresh": "2021-10-07T01:35:13.000Z",
    "disabled": false,
    "createdAt": "2021-10-07T01:35:13.389Z",
    "updatedAt": "2021-10-07T01:35:13.389Z"
  },
  "newUserLink": "https://demo.immuta.com/login?token=******&userid=charlie.doe%40immuta.com&name=Charlie%20Doe",
  "emailFailed": false,
  "emailSent": false
}

Manage users

Method

Path

Purpose

Authenticate a user from an outside IAM

GET /bim/iam/{iamid}/user/authenticate

Authenticate a user from a 3rd-party identity provider.

Request parameters

Attribute

Description

Required

Request example

This example request

curl \
  --request POST \
  --header "Content-Type: application/json" \
  https://demo.immuta.com/LDAPIAM/user/authenticate

Authenticate user with username and password

POST /bim/iam/{iamid}/user/authenticate

Authenticate a user using their username and password and proxying it to the specified IAM service.

Request parameters

Attribute

Description

Required

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request with the payload below will authenticate the user using the bim IAM.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --data @example-payload.json \
  https://demo.immuta.com/bim/iam/bim/user/authenticate

Payload example

{
  "username": "demo.user@immuta.com",
  "password": "********"
}

Response example

{
  "authenticated": true,
  "token": "6913229***********0d3da",
  "tokenExpiration": "2021-09-29T19:12:51.467Z"
}

Update a user profile

PUT /bim/iam/{iamid}/user/{userid}/profile

Update a specified user's profile.

Request parameters

Attribute

Description

Required

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will change the location to Boston, MA for the user with the username jane.doe@immuta.com.

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe@immuta.com/profile

Payload example

{
  "email": "jane.doe@immuta.com",
  "phone": null,
  "about": null,
  "location": "Boston, MA",
  "organization": null,
  "position": "",
  "preferences": {
    "sortDataSourceState": {
      "column": "name",
      "order": "asc",
      "size": 12
    },
    "sortProjectDataSourceState": {
      "column": "dataSourceName",
      "order": "asc",
      "size": 12
    },
    "sortProjectState": {
      "column": "name",
      "order": "asc",
      "size": 12
    },
    "notifications": {
      "email": false
    },
    "tabDataSourceState": 0,
    "tabProjectState": 0,
    "dataSourceOverrides": {},
    "showPolicySearchDetailLabels": true
  },
  "externalUserIds": {},
  "scim": null,
  "systemGenerated": false,
  "iamid": "bim",
  "userid": "jane.doe@immuta.com"
}

Response example

{
  "name": "Jane Doe",
  "email": "jane.doe@immuta.com",
  "phone": null,
  "about": null,
  "location": "Boston, MA",
  "organization": null,
  "position": null,
  "externalUserIds": {},
  "systemGenerated": false,
  "id": 2,
  "createdAt": "2021-08-16T20:30:43.698Z",
  "updatedAt": "2021-10-18T20:49:06.237Z",
  "preferences": {
    "sortProjectState": {
      "column": "name",
      "order": "asc",
      "size": 12
    },
    "currentProject": null,
    "sortDataSourceState": {
      "column": "name",
      "order": "asc",
      "size": 12
    },
    "sortProjectDataSourceState": {
      "column": "dataSourceName",
      "order": "asc",
      "size": 12
    },
    "notifications": {
      "email": false
    },
    "tabDataSourceState": 0,
    "tabProjectState": 0,
    "dataSourceOverrides": {},
    "showPolicySearchDetailLabels": true
  },
  "scim": null
}

Remove a user's permissions

DELETE /bim/iam/{iamid}/user/{userid}/permissions/{permission}

Remove the specified user's permission.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will delete the permission CREATE_DATA_SOURCE_IN_PROJECT from the user with the username john.doe@immuta.com.

curl \
  --request DELETE \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/john.doe%40immuta.com/permissions/CREATE_DATA_SOURCE_IN_PROJECT

Response example

{
  "id": 3,
  "iamid": "bim",
  "userid": "john.doe@immuta.com",
  "bimAuthorizations": null,
  "iamAuthorizations": null,
  "authorizations": {},
  "permissions": [
    "CREATE_PROJECT",
    "CREATE_DATA_SOURCE"
  ],
  "profile": 3,
  "authentication": 3,
  "systemGenerated": false,
  "lastLogin": "2021-09-27T15:29:00.154Z",
  "lastExternalRefresh": "2021-09-27T15:29:00.154Z",
  "disabled": false,
  "createdAt": "2021-08-19T19:33:38.582Z",
  "updatedAt": "2021-10-06T22:03:48.611Z"
}

Update a user's permissions

PUT /bim/iam/{iamid}/user/{userid}/permissions

Update the specified user's permission.

Request parameters

Attribute

Description

Required

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request with the payload below will change to permissions of the user with the username charlie.doe@immuta.com to CREATE_DATA_SOURCE_IN_PROJECT, CREATE_PROJECT, and CREATE_DATA_SOURCE.

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/charlie.doe%40immuta.com/permissions

Payload example

[
  "CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT", "CREATE_DATA_SOURCE"
]

Response example

{
  "id": 18,
  "iamid": "bim",
  "userid": "charlie.doe@immuta.com",
  "bimAuthorizations": null,
  "iamAuthorizations": null,
  "authorizations": {},
  "permissions": [
    "CREATE_DATA_SOURCE_IN_PROJECT",
    "CREATE_PROJECT",
    "CREATE_DATA_SOURCE"
  ],
  "profile": 18,
  "authentication": null,
  "systemGenerated": false,
  "lastLogin": null,
  "lastExternalRefresh": "2021-10-07T01:35:13.000Z",
  "disabled": false,
  "createdAt": "2021-10-07T01:35:13.389Z",
  "updatedAt": "2021-10-07T16:10:40.214Z"
}

Update a user's password

PUT /bim/iam/{iamid}/user/{userid}/password

Update the specified user's password.

Request parameters

Attribute

Description

Required

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request with the payload below will change the password of the user with the ID jane.doe@immuta.com.

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe%40immuta.com/password

Payload example

{
  "originalPassword": "old********",
  "password": "new********"
}

Response example

{
  "success": true
}

Disable or enable a user

PUT /bim/iam/{iamid}/user/{userid}/disable/{disable}

Disable / enable the specified BIM user.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will disabled the user with the username jane.doe@immuta.com.

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe%40immuta.com/disable/true

Response example

{
  "userid": "jane.doe@immuta.com",
  "disabled": true
}

Sync users from an external IAM

POST /bim/syncUsers

Sync users from an external IAM.

Payload parameters

Attribute

Description

Required

Request example

This example request will sync the users from the specified external IAM with Immuta.

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

Payload example

{
  "iamid": "ldap"
}

Sync LDAP users with Immuta

POST /iam/{iamId}/sync

Sync LDAP users with Immuta.

Request parameters

Attribute

Description

Required

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will sync the users from Jump Cloud with Immuta.

curl -X 'POST' \
  'https://demo.immuta.com/iam/JumpCloud/sync' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 496ac257b8db4a96a16715fb4ed048dc' \

Payload example

{
  "dryRun": true,
  "iamConfig": {
    "authenticationOnly": false,
    "credentials": {
      "bind_dn": "uid=bind-user,ou=Users,o=redacted,dc=jumpcloud,dc=com"
    },
    "defaultPermissions": ["CREATE_DATA_SOURCE", "CREATE_PROJECT"],
    "displayName": "Jump Cloud LDAP",
    "id": "jumpcloudLDAPIAM",
    "ldapSync": {},
    "options": {
      "groupSearchFilter": "(&(objectClass=groupOfNames)(cn=%s*))",
      "host": "ldap.jumpcloud.com",
      "port": 636,
      "useSSL": true,
      "userGroupSearchFilter": "(member=<dn>)",
      "userSearchBase": "o=redacted,dc=jumpcloud,dc=com",
      "userSearchFilter": "mail=%s",
      "allowIdPInitiatedSSO": false
    },
    "plugin": "ldap",
    "schema": {
      "group": {
        "name": "cn"
      },
      "profile": {
        "email": "mail",
        "name": "cn",
        "phone": "phone"
      },
      "authorizations": {},
      "externalUserIds": {}
    },
    "supportedActions": ["syncGroups"],
    "type": "ldap"
  }
}

Response example

{
  "totalCount": 10,
  "importedUsers": [{
    "userId": "user-1@example.com",
    "dn": "uid=user-1,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "user-2@example.com",
    "dn": "uid=user-2,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "user-3@example.com",
    "dn": "uid=user-3,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "user-4@example.com",
    "dn": "uid=user-4,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "user-5@example.com",
    "dn": "uid=user-5,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }],
  "refreshedUsers": [],
  "disabledUsers": [],
  "enabledUsers": [],
  "count": 5
}

Update a user's or group's attributes

PUT /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue}

Update the specified user's attributes.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will add the attribute Finance.Red Team to the user with the username jane.doe@immuta.com.

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe@immuta.com/authorizations/Finance/Red%20Team

Response example

{
  "id": 16,
  "iamid": "bim",
  "userid": "jane.doe@immuta.com",
  "bimAuthorizations": {
    "Finance": ["CFA", "Red Team"]
  },
  "iamAuthorizations": null,
  "authorizations": {
    "Finance": ["CFA", "Red Team"]
  },
  "permissions": ["CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT"],
  "profile": 16,
  "authentication": 5,
  "systemGenerated": false,
  "lastLogin": "2021-10-07T02:58:31.708Z",
  "lastExternalRefresh": "2021-10-07T02:58:31.708Z",
  "disabled": false,
  "createdAt": "2021-10-06T22:17:46.500Z",
  "updatedAt": "2021-10-18T17:09:53.711Z"
}

Remove a user or group's attribute

DELETE /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value}

Remove an attribute from the specified group or user.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will remove the attribute Country.JP from the user with the user ID jane.doe@immuta.com.

curl \
  --request DELETE \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe@demo.com/authorizations/Country/JP

Response example

{
  "id": 4,
  "iamid": "bim",
  "userid": "jane.doe@demo.com",
  "bimAuthorizations": {
    "Country": ["US"],
    "Environment": ["Dev"],
    "OfficeLocation": ["Japan"]
  },
  "iamAuthorizations": null,
  "authorizations": {
    "Country": ["US"],
    "Environment": ["Dev"],
    "OfficeLocation": ["Japan"]
  },
  "permissions": ["CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT", "USER_ADMIN", "GOVERNANCE"],
  "profile": 4,
  "authentication": 3,
  "systemGenerated": false,
  "lastLogin": "2022-08-11T01:36:01.947Z",
  "lastExternalRefresh": "2022-08-11T01:36:01.947Z",
  "disabled": false,
  "createdAt": "2022-06-02T17:37:24.515Z",
  "updatedAt": "2022-08-11T18:40:51.366Z"
}

Clone user

Configure SMTP: SMTP must be configured to use this endpoint. Additionally, after the users are created, they will not be active until they sign in to the Immuta UI.

POST /bim/iam/bim/user/{userid}/clone

Clones the provided user (including their permissions, groups, and attributes) to create multiple additional user accounts.

Request parameters

Attribute

Description

Required

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will clone the user with the username jane.doe@immuta.com.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe%40demo.com/clone

Payload example

[
  "john.doe@demo.com"
]

Response example

{
  "failedEmails": []
}

Review user information

Method

Path

Purpose

Search all IAMs

GET /bim/iam

Get a listing of configured IAM services.

Response parameters

Attribute

Description

Request example

The request below will list all of the IAMs in use.

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

Response example

[
  {
    "id": "bim",
    "displayName": "Immuta",
    "type": "built-in",
    "oauth": false
  },
  {
    "id": "oktaSamlIAM",
    "displayName": "Okta SAML",
    "type": "saml",
    "oauth": false
  },
  {
    "id": "ldap",
    "displayName": "LDAP",
    "type": "ldap"
  }
]

Search all users

GET /bim/user

Administrative search over the aggregated view of all users.

Query parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

The request below will search all of the users in Immuta.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/user?size=25&name=bar&sortOrder=asc

Response example

{
  "count": "2",
  "hits": [
    {
      "id": 18,
      "iamid": "bim",
      "userid": "bspringer@immuta.com",
      "permissions": [
        "CREATE_DATA_SOURCE",
        "CREATE_PROJECT"
      ],
      "profile": {
        "name": "Barrett Springer",
        "email": "bspringer@immuta.com",
        "id": 18,
        "createdAt": "2018-07-05T07:37:06.569Z",
        "updatedAt": "2018-07-05T07:37:06.569Z"
      },
      "authentication": 18,
      "systemGenerated": false,
      "lastLogin": "2018-07-05T07:39:56.365Z",
      "disabled": false,
      "createdAt": "2018-07-05T07:37:05.987Z",
      "updatedAt": "2018-07-05T07:37:05.987Z"
    },
    {
      "id": 5,
      "iamid": "bim",
      "userid": "bhoward@immuta.com",
      "authorizations": {
        "auth": [
          "SOMETHING_ELSE"
        ]
      },
      "permissions": [
        "CREATE_DATA_SOURCE",
        "CREATE_PROJECT",
        "AUDIT"
      ],
      "profile": {
        "name": "Barry Howard",
        "email": "bhoward@immuta.com",
        "preferences": {
          "sortDataSourceState": {
            "column": "name",
            "order": "asc",
            "size": 12
          },
          "sortProjectState": {
            "column": "name",
            "order": "asc",
            "size": 12
          }
        },
        "id": 5,
        "createdAt": "2018-07-05T07:37:06.392Z",
        "updatedAt": "2018-07-05T22:32:43.864Z"
      },
      "authentication": 5,
      "systemGenerated": false,
      "lastLogin": "2018-07-05T22:32:44.167Z",
      "disabled": false,
      "createdAt": "2018-07-05T07:37:05.818Z",
      "updatedAt": "2018-07-05T07:37:05.818Z"
    }
  ]
}

View current user's information

GET /bim/rpc/user/current

Get the currently logged in user's information.

Response parameters

Attribute

Description

Request example

This request will return information on the user that is logged in.

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

Response example

{
  "profile": {
    "name": "Barrett Springer",
    "email": "bspringer@immuta.com",
    "phone": null,
    "about": null,
    "location": null,
    "organization": null,
    "position": null,
    "preferences": null,
    "hdfsUser": null,
    "id": 18,
    "createdAt": "2018-07-05T07:37:06.569Z",
    "updatedAt": "2018-07-05T07:37:06.569Z"
  },
  "permissions": [
    "CREATE_DATA_SOURCE",
    "CREATE_PROJECT"
  ],
  "authorizations": {
    "Roles": [
      "Analyst"
    ],
    "Location": [
      "Columbus"
    ]
  },
  "iamid": "bim",
  "userid": "bspringer@immuta.com",
  "authorizations": null,
  "updatedAt": "2018-07-05T07:37:05.987Z",
  "systemGenerated": false,
  "disabled": false,
  "hasLogin": true,
  "lastLogin": "2018-07-05T07:39:56.365Z"
}

View a user's information

GET /bim/iam/{iamid}/user/{id}

Gets the specified user's aggregated view.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will return information about the user with the ID 2.

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

Response example

{
  "profile": {
    "name": "John Doe",
    "email": "john.doe@immuta.com",
    "phone": null,
    "about": null,
    "location": null,
    "organization": null,
    "position": null,
    "preferences": {
      "sortProjectState": {
        "column": "name",
        "order": "asc",
        "size": 12
      },
      "currentProject": null
    },
    "externalUserIds": {},
    "scim": null,
    "systemGenerated": false,
    "id": 2,
    "createdAt": "2021-08-16T20:30:43.698Z",
    "updatedAt": "2021-09-14T01:17:02.786Z"
  },
  "permissions": [
    "CREATE_DATA_SOURCE_IN_PROJECT",
    "CREATE_PROJECT",
    "CREATE_DATA_SOURCE",
    "USER_ADMIN",
    "APPLICATION_ADMIN",
    "AUDIT",
    "GOVERNANCE",
    "IMPERSONATE_HDFS_USER",
    "CREATE_S3_DATASOURCE_WITH_INSTANCE_ROLE",
    "FETCH_POLICY_INFO",
    "CREATE_FILTER",
    "IMPERSONATE_USER",
    "PROJECT_MANAGEMENT"
  ],
  "iamid": "bim",
  "userid": "jane.doe@immuta.com",
  "authorizations": {},
  "updatedAt": "2021-09-29T17:57:09.059Z",
  "systemGenerated": false,
  "disabled": false,
  "lastLogin": "2021-09-30T19:20:03.327Z",
  "lastExternalRefresh": "2021-09-30T19:20:03.327Z",
  "bimAuthorizations": null,
  "iamAuthorizations": null,
  "hasLogin": true
}

View a user profile

GET /bim/iam/{iamid}/user/{userid}/profile

Gets the specified user's profile.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will return the profile of the user with the ID 2.

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

Response example

{
  "name": "John Doe",
  "email": "john.doe@immuta.com",
  "phone": null,
  "about": null,
  "location": null,
  "organization": null,
  "position": null,
  "preferences": {
    "sortProjectState": {
      "column": "name",
      "order": "asc",
      "size": 12
    },
    "currentProject": null
  },
  "externalUserIds": {},
  "scim": null,
  "systemGenerated": false,
  "id": 2,
  "createdAt": "2021-08-16T20:30:43.698Z",
  "updatedAt": "2021-09-14T01:17:02.786Z"
}

View a user's groups

GET /bim/iam/{iamid}/user/{userid}/groups

Get the specified user's list of groups.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will return information on the groups of the user with the username john.doe@immuta.com.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/john.doe%40immuta.com/groups

Response example

[
  {
    "id": 2,
    "name": "API Group #2",
    "iamid": "bim",
    "groupUser": 6
  }
]

Delete a user

DELETE /bim/iam/bim/user/{userid}

Delete the specified user in Immuta.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will delete the user with the username charlie.doe@immuta.com.

curl \
  --request DELETE \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/charlie.doe%40immuta.com

Response example

{
  "userid": "charlie.doe@immuta.com",
  "iamid": "bim"
}

Create a new group

POST /bim/group

Create a new group.

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This request with the payload below will create a group through the bim IAM with the name API Group.

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

Payload example

{
  "iamid": "bim",
  "name": "API Group"
}

Response example

{
  "id": 3,
  "iamid": "bim",
  "name": "API Group",
  "gid": null,
  "email": null,
  "authorizations": null,
  "description": null,
  "scim": null,
  "scimid": null,
  "createdAt": "2021-09-29T15:15:26.615Z",
  "updatedAt": "2021-09-29T15:15:26.615Z"
}

Manage groups

Method

Path

Purpose

Update a group

PUT /bim/group/{groupId}

Update the specified group.

Request parameters

Attribute

Description

Required

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This request with the payload below will update the group with the ID 2 with the name API Group #2 and with a new description.

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

Payload example

{
  "name": "API Group #2",
  "description": "This group was edited through the API"
}

Response example

{
  "id": 2,
  "iamid": "bim",
  "name": "API Group #2",
  "gid": null,
  "email": "blue.team@immuta.com",
  "authorizations": {
    "Finance": [
      "CFA"
    ]
  },
  "description": "This group was edited through the API",
  "scim": null,
  "scimid": null,
  "createdAt": "2021-09-16T17:24:55.066Z",
  "updatedAt": "2021-09-29T17:32:07.725Z"
}

Remove a user from a group

DELETE /bim/group/{groupId}/user/{groupuserid}

Remove a user from a group.

Request parameters

Attribute

Description

Required

Request example

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/group/1/user/2

Add a user to a group

POST /bim/group/{groupId}/user

Add a new user to a group.

Request parameters

Attribute

Description

Required

Payload parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This request with the payload below adds the user with the ID tom.jones@immuta.com to the group with the ID 2.

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

Payload example

{
  "userid": "tom.jones@immuta.com",
  "iamid": "bim"
}

Response example

{
  "id": 6,
  "group": 2,
  "profile": 2,
  "createdAt": "2021-09-29T17:57:09.054Z",
  "updatedAt": "2021-09-29T17:57:09.054Z"
}

Update a group's attributes

PUT /bim/iam/{iamid}/group/{groupid}/authorizations/{attributeName}/{attributeValue}

Update the specified group's attributes.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will add the attribute Finance.Red Team to the group with the ID 2.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/iam/bim/group/2/authorizations/Finance/Red%20Team

Response example

{
  "id": 2,
  "iamid": "bim",
  "name": "API Group #2",
  "gid": null,
  "email": "blue.team@immuta.com",
  "authorizations": {
    "Finance": ["CFA", "Red Team"]
  },
  "description": "This group was edited through the API",
  "scim": null,
  "scimid": null,
  "createdAt": "2021-09-16T17:24:55.066Z",
  "updatedAt": "2021-10-08T13:41:06.211Z"
}

Search groups

Method

Path

Purpose

Search all groups from all IAMs

GET /bim/group

Get the list of groups from all configured IAMs.

Query parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This request will return all of the groups in Immuta.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/group?size=25&sortOrder=asc

Response example

{
  "count": "3",
  "hits": [
    {
      "id": 2,
      "iamid": "bim",
      "name": "engineers",
      "gid": null,
      "email": "engineers@immuta.com",
      "authorizations": null,
      "description": null,
      "createdAt": "2018-07-05T07:37:07.209Z",
      "updatedAt": "2018-07-05T07:37:07.209Z"
    },
    {
      "id": 1,
      "iamid": "bim",
      "name": "founders",
      "gid": null,
      "email": null,
      "authorizations": null,
      "description": null,
      "createdAt": "2018-07-05T07:37:07.177Z",
      "updatedAt": "2018-07-05T07:37:07.177Z"
    },
    {
      "id": 20,
      "iamid": "bim",
      "name": "system administrators",
      "gid": null,
      "email": null,
      "authorizations": null,
      "description": null,
      "createdAt": "2018-07-05T07:37:07.595Z",
      "updatedAt": "2018-07-05T07:37:07.595Z"
    }
  ]
}

Search a specific group

GET /bim/group/{groupid}

Get the specified group.

Query parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This request will search for the group with the ID 2.

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

Response example

{
  "id": 2,
  "iamid": "bim",
  "name": "engineers",
  "gid": null,
  "email": "engineers@immuta.com",
  "authorizations": {
    "Location": [
      "College Park"
    ]
  },
  "description": null,
  "createdAt": "2018-07-05T07:37:07.209Z",
  "updatedAt": "2018-07-06T01:42:55.518Z"
}

Search a group's users

GET /bim/group/{groupid}/user

Get group users.

Query parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This request will return information on the users in the group with the ID 2.

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

Response example

{
  "count": 2,
  "hits": [
    {
      "id": 1,
      "group": 2,
      "profile": {
        "name": "Willie Gomez",
        "email": "wgomez@immuta.com",
        "phone": null,
        "about": null,
        "location": null,
        "organization": null,
        "position": null,
        "preferences": {
          "tabDataSourceState": 1,
          "tabProjectState": 1
        },
        "hdfsUser": "wgomez",
        "id": 3,
        "createdAt": "2018-07-05T07:37:06.373Z",
        "updatedAt": "2018-07-05T07:37:06.373Z"
      },
      "createdAt": "2015-08-23T00:00:00.000Z",
      "updatedAt": "2018-07-05T07:37:07.283Z",
      "userid": "wgomez@immuta.com",
      "iamid": "bim"
    },
    {
      "id": 2,
      "group": 2,
      "profile": {
        "name": "Helen James",
        "email": "hjames@immuta.com",
        "phone": null,
        "about": null,
        "location": null,
        "organization": null,
        "position": null,
        "preferences": null,
        "hdfsUser": null,
        "id": 13,
        "createdAt": "2018-07-05T07:37:06.470Z",
        "updatedAt": "2018-07-05T07:37:06.470Z"
      },
      "createdAt": "2018-07-05T07:37:07.291Z",
      "updatedAt": "2018-07-05T07:37:07.291Z",
      "userid": "hjames@immuta.com",
      "iamid": "bim"
    }
  ]
}

Delete a group

DELETE /bim/group/{groupId}

Delete the specified group.

Query parameters

Attribute

Description

Required

Request example

This request will delete the group with the ID 3.

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

Authenticate a user and create a project API key

POST /bim/apikey

Authenticate the user and create a project API key.

Payload parameters

Attribute

Description

Required

The payload must have one or both of the two attributes above.

Response parameters

Attribute

Description

Request example

This example request with the payload below will authenticate the user Jane Doe in the project with the ID 1 and create a new API key for her.

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

Payload example

{
  "projectId": 1,
  "name": "My Project API Key"
}

Response example

{
  "apikey": "******",
  "keyid": 334,
  "project": 1,
  "name": "My Project API Key",
  "context": null
}

Authenticate with an API key

Method

Path

Purpose

Authenticate a user with an API key

POST /bim/apikey/authenticate

Authenticate with the Immuta API using an API key.

Payload parameters

Attribute

Description

Response parameters

Attribute

Description

Request example

This example request will authenticate the user with the Immuta API.

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

Payload example

{
  "apikey": "100874dyour-api-key-79aa38bbfe0e8c787"
}

Response example

{
  "authenticated": true,
  "token": "be420************2745ea0307"
}

Impersonate a user with an API key

POST /bim/apikey/impersonate

Impersonate another user using an API key.

Payload parameters

Attribute

Description

Response parameters

Attribute

Description

Request example

This example request will allow the requesting user to impersonate the user specified in example-payload.json.

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

Payload example

{
  "apikey": "requesting-users-api-key",
  "userid": "user1@example.com",
  "iamid": "bim"
}

Response example

{
  "authenticated": true,
  "token": "0753*************c61d2"
}

View tokens and API keys

Method

Path

Purpose

View token information

POST /bim/token

Get information for a given token, should it exist.

Payload parameters

Attribute

Description

Response parameters

Attribute

Description

Request example

This example request will return information on the access token in the payload.

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

Payload example

{
  "token": "48983da*********85220837d"
}

Response example

{
  "id": 384,
  "type": "bearer",
  "iamid": "bim",
  "userid": "jane.doe@immuta.com",
  "project": null,
  "context": null,
  "token": "4898*********220837d",
  "created": "2021-10-15T03:59:03.000Z",
  "lastUsed": "2021-10-15T03:59:57.185Z",
  "expiration": "2021-10-15T04:59:57.185Z",
  "name": null,
  "application": null,
  "derivedFrom": null,
  "createdAt": "2021-10-15T03:59:03.562Z",
  "updatedAt": "2021-10-15T03:59:57.186Z",
  "scopes": null,
  "impersonationuserid": null,
  "impersonationiamid": null
}

View a user's API keys

GET /bim/iam/{iamid}/user/{userid}/apikeys

Get metadata for all of the user's API keys.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will return information on the API keys of the user with the username john.doe@immuta.com.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/john.doe%40immuta.com/apikeys

Response example

[
  {
    "keyid": 323,
    "created": "2021-10-06T18:28:13.000Z",
    "project": {
      "projectKey": "Credit Payments",
      "name": "Credit Payments",
      "status": "open",
      "description": "This project contains all data sources under the schema, credit_payments, from admin@snowflake.demo-databases.prod.immuta.com:3306/credit_payments.",
      "documentation": "This is an automatically generated project that collects data sources under the schema, credit_payments, from admin@snowflake.demo-databases.prod.immuta.com:3306/credit_payments. 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,
      "salt": "e0c4a8c5-2a5b-4488-9c43-cb3d816172f4",
      "type": "Schema",
      "schema": "credit_payments",
      "id": 3,
      "createdAt": "2021-09-09T17:06:39.839Z",
      "updatedAt": "2021-09-09T17:06:39.839Z",
      "workspace": null,
      "createdBy": 2,
      "updatedBy": 2,
      "schemaEvolutionId": 2
    },
    "lastUsed": "2021-10-06T18:28:13.341Z",
    "name": "Credit Payments",
    "context": null
  }
]

Delete an API key

DELETE /bim/apikey/{keyid}

Delete an API key, all auth tokens issued using that API key, and generate a new API key.

Request parameters

Attribute

Description

Required

Response parameters

Attribute

Description

Request example

This example request will delete the API key with the ID 323, revoke all the auth tokens issued using that API key, and generate a new API key.

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

Response example

{
  "revokedTokens": 1
}

Sensitive Data Discovery

In previous documentation, rule and pattern are referred to as classifier or identifier, and framework is referred to as template.

Workflow

Create a pattern.
Create an identification framework containing one or more rules.
Search for pattern or identification frameworks.
Apply an identification framework to one or more data sources.
Run SDD on one or more data sources; tags are applied to columns where rules were found.
Update patterns or identification frameworks.
Delete patterns or identification frameworks.

Create a pattern

To run this pattern against your data, ensure it is added to a framework.

POST /sdd/classifier

Create a pattern.

Payload parameters

Attribute

Description

Required

Response parameters

Request example

The following request creates a pattern, saved in example-payload.json.

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

Payload examples

{
  "name": "MY_REGEX_PATTERN",
  "displayName": "My Regex Pattern",
  "description": "A regex pattern example",
  "type": "regex",
  "config": {
    "regex": "^[A-Z][a-z]+",
    "tags": ["Discovered.regex-example"]
  }
}

{
  "name": "MY_DICTIONARY_PATTERN",
  "displayName": "My Dictionary Pattern",
  "description": "A dictionary pattern example",
  "type": "dictionary",
  "config": {
    "values": ["Bob", "Eve"],
    "caseSensitive": true,
    "tags": ["Discovered.dictionary-example", "Discovered.dictionary-pattern-example"]
  }
}

{
  "name": "MY_COLUMN_NAME_PATTERN",
  "displayName": "My Column Name Pattern",
  "description": "A column name pattern example",
  "type": "columnNameRegex",
  "config": {
    "columnNameRegex": "ssn|social ?security",
    "tags": ["Discovered.column-name-regex"]
  }
}

Response example

{
  "createdBy": {
    "id": 1,
    "name": "John",
    "email": "john@example.com"
  },
  "name": "MY_REGEX_PATTERN",
  "displayName": "My Regex Pattern",
  "description": "A regex pattern example",
  "type": "regex",
  "config": {
    "tags": [
      "Discovered.regex-example"
    ],
    "regex": "^[A-Z][a-z]+"
  },
  "id": 67,
  "createdAt": "2021-10-14T18:48:56.289Z",
  "updatedAt": "2021-10-14T18:48:56.289Z"
}

Create an identification framework

POST /sdd/template

Create an identification framework.

Payload parameters

Response parameters

Request example

The following request creates an identification framework that contains 2 rules, saved in example-payload.json.

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

Payload example

{
  "name": "MY_FIRST_FRAMEWORK",
  "displayName": "My First Framework",
  "description": "This is the first framework I've created.",
  "classifiers": [
    {
      "name": "MY_COLUMN_NAME_PATTERN"
    },
    {
      "name": "MY_REGEX_PATTERN"
    },
    {
      "name": "AGE",
      "overrides": {
        "tags": [
          "Discovered.Entity.Age"
        ]
      }
    }
  ]
}

Response example

{
  "name": "MY_FIRST_FRAMEWORK",
  "displayName": "My First Framework",
  "description": "This is the first framework I've created.",
  "createdBy": {
    "id": 1,
    "name": "John",
    "email": "john@example.com"
  },
  "id": 1,
  "createdAt": "2021-10-14T19:12:22.092Z",
  "updatedAt": "2021-10-14T19:12:22.092Z",
  "classifiers": [
    {
      "name": "MY_COLUMN_NAME_REGEX_PATTERN",
      "overrides": {}
    },
    {
      "name": "MY_REGEX_PATTERN",
      "overrides": {}
    }
  ]
}

Search for patterns or identification frameworks

List or search for patterns

GET /sdd/classifier

List or search patterns.

Query parameters

Response parameters

Request example

The following request lists 5 patterns.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.immuta.com/sdd/classifier?sortField=name&sortOrder=asc&limit=5

Response example

{
  "count": 67,
  "hits": [
    {
      "createdBy": {
        "id": 21,
        "name": "Immuta System Account",
        "email": "immuta_system@immuta.com"
      },
      "name": "AGE",
      "displayName": "Age",
      "description": "Matches numeric strings between 10 and 199.",
      "type": "builtIn",
      "config": {
        "tags": [
          "Discovered.PII",
          "Discovered.Identifier Indirect",
          "Discovered.PHI",
          "Discovered.Entity.Age"
        ],
        "conditionalTags": {}
      },
      "id": 3,
      "createdAt": "2021-10-28T07:34:58.761Z",
      "updatedAt": "2021-10-28T07:34:58.761Z"
    },
    {
      "createdBy": {
        "id": 21,
        "name": "Immuta System Account",
        "email": "immuta_system@immuta.com"
      },
      "name": "ARGENTINA_DNI_NUMBER",
      "displayName": "Argentina DNI Number",
      "description": "Matches strings consistent with Argentina National Identity (DNI) Number.  Requires an eight digit number with optional periods between the second and third and fifth and sixth digit.",
      "type": "builtIn",
      "config": {
        "tags": [
          "Discovered.PII",
          "Discovered.Identifier Direct",
          "Discovered.Country.Argentina",
          "Discovered.PHI",
          "Discovered.Entity.DNI Number"
        ],
        "conditionalTags": {}
      },
      "id": 4,
      "createdAt": "2021-10-28T07:34:58.769Z",
      "updatedAt": "2021-10-28T07:34:58.769Z"
    },
    {
      "createdBy": {
        "id": 21,
        "name": "Immuta System Account",
        "email": "immuta_system@immuta.com"
      },
      "name": "AUSTRALIA_MEDICARE_NUMBER",
      "displayName": "Australia Medicare Number",
      "description": "Matches numeric strings consistent with Australian Medicare Number.  Requires a ten or eleven digit number.  The starting digit must be between 2 and 6, inclusive.  Optional spaces can be placed between the fourth and fifth and ninth and tenth digit.  Optional 11th separated by a `/` can be present.  A checksum is required.",
      "type": "builtIn",
      "config": {
        "tags": [
          "Discovered.PII",
          "Discovered.Identifier Direct",
          "Discovered.Country.Australia",
          "Discovered.PHI",
          "Discovered.Entity.Medicare Number"
        ],
        "conditionalTags": {}
      },
      "id": 5,
      "createdAt": "2021-10-28T07:34:58.779Z",
      "updatedAt": "2021-10-28T07:34:58.779Z"
    },
    {
      "createdBy": {
        "id": 21,
        "name": "Immuta System Account",
        "email": "immuta_system@immuta.com"
      },
      "name": "AUSTRALIA_PASSPORT",
      "displayName": "Australia Passport",
      "description": "Matches strings consistent with Australian Passport number.  A 8 or 9 character string is required, with a starting upper case character (N, E, D, F, A, C, U, X) or a two character starting character (P followed by A, B, C, D, E, F, U, W, X, or Z) followed by seven digits",
      "type": "builtIn",
      "config": {
        "tags": [
          "Discovered.PII",
          "Discovered.Identifier Direct",
          "Discovered.Country.Australia",
          "Discovered.PHI",
          "Discovered.Entity.Passport"
        ],
        "conditionalTags": {}
      },
      "id": 26,
      "createdAt": "2021-10-28T07:34:59.010Z",
      "updatedAt": "2021-10-28T07:34:59.010Z"
    },
    {
      "createdBy": {
        "id": 21,
        "name": "Immuta System Account",
        "email": "immuta_system@immuta.com"
      },
      "name": "AUSTRALIA_TAX_FILE_NUMBER",
      "displayName": "Australia Tax File Number",
      "description": "Matches strings consistent with Australia Tax File Number.  Requires a nine digit number with optional spaces between the third and fourth and sixth and seventh digits.  A checksum is also required",
      "type": "builtIn",
      "config": {
        "tags": [
          "Discovered.PII",
          "Discovered.Identifier Direct",
          "Discovered.Country.Australia",
          "Discovered.PHI",
          "Discovered.Entity.Tax File Number"
        ],
        "conditionalTags": {}
      },
      "id": 6,
      "createdAt": "2021-10-28T07:34:58.789Z",
      "updatedAt": "2021-10-28T07:34:58.789Z"
    }
  ]
}

List or search for identification frameworks

GET /sdd/template

List or search identification frameworks.

Query parameters

Response parameters

Request example

The following request lists all identification frameworks.

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

Response example

{
  "count": 1,
  "hits": [
    {
      "name": "MY_FIRST_FRAMEWORK",
      "displayName": "My First Framework",
      "description": "This is the first framework I've created.",
      "createdBy": {
        "id": 1,
        "name": "John",
        "email": "john@example.com"
      },
      "id": 1,
      "createdAt": "2021-10-14T19:12:22.092Z",
      "updatedAt": "2021-10-14T19:12:22.092Z",
      "classifiers": [
        {
          "name": "MY_COLUMN_NAME_PATTERN",
          "overrides": {}
        },
        {
          "name": "MY_REGEX_PATTERN",
          "overrides": {}
        }
      ]
    }
  ]
}

View a pattern by name

GET /sdd/classifier/{classifierName}

Get a pattern by name.

Query parameters

Response parameters

Request example

This request gets the pattern named MY_REGEX_PATTERN.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.immuta.com/sdd/classifier/MY_REGEX_PATTERN

Response example

{
  "createdBy": {
    "id": 1,
    "name": "John",
    "email": "john@example.com"
  },
  "name": "MY_REGEX_PATTERN",
  "displayName": "My Regex Pattern",
  "description": "A regex pattern example",
  "type": "regex",
  "config": {
    "tags": [
      "Discovered.regex-example"
    ],
    "regex": "^[A-Z][a-z]+"
  },
  "id": 67,
  "createdAt": "2021-10-18T16:48:18.819Z",
  "updatedAt": "2021-10-18T16:48:18.819Z"
}

View an identification framework by name

GET /sdd/template/{templateName}

Get an identification framework by name.

Query parameters

Response parameters

Request example

This request gets the identification framework named MY_FIRST_FRAMEWORK.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.immuta.com/sdd/template/MY_FIRST_FRAMEWORK

Response example

{
  "name": "MY_FIRST_FRAMEWORK",
  "displayName": "My First Framework",
  "description": "This is the first framework I've created.",
  "createdBy": {
    "id": 1,
    "name": "John",
    "email": "john@immuta.com"
  },
  "id": 1,
  "createdAt": "2021-10-18T16:54:24.920Z",
  "updatedAt": "2021-10-18T16:54:24.920Z",
  "classifiers": [
    {
      "name": "MY_DICTIONARY_PATTERN",
      "overrides": {}
    },
    {
      "name": "MY_REGEX_PATTERN",
      "overrides": {}
    }
  ]
}

View the current global framework

GET /sdd/template/global

View the current global framework.

Response parameters

Request example

This request gets the current global framework information.

curl -X 'GET' \
  'https://demo.immuta.com/sdd/template/global' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 9ba76f3c64c345ad817fa467d7110556'

Response example

{
  "name": "MY_FIRST_FRAMEWORK",
  "displayName": "My First Framework",
  "description": "This is the first framework I've created.",
  "createdBy": {
    "id": 2,
    "name": "Jane Doe",
    "email": "jane.doe@immuta.com"
  },
  "id": 1,
  "createdAt": "2022-08-10T20:35:43.252Z",
  "updatedAt": "2022-08-10T20:35:43.252Z",
  "classifiers": [
    {
      "name": "AGE",
      "overrides": {}
    },
    {
      "name": "ETHNIC_GROUP",
      "overrides": {}
    }
  ]
}

Apply identification frameworks to data sources

PUT /sdd/template/apply

Apply an identification framework to a set of data sources.

Payload parameters

Response parameters

Request example

This request applies the MY_FIRST_FRAMEWORK framework to the Public Case data source.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.immuta.com/sdd/template/apply

Payload example

{
  "template": "MY_FIRST_FRAMEWORK",
  "sources": [
    "Public Case"
  ]
}

Response example

{
  "success": true
}

Run SDD on data sources

POST /sdd/run

Run SDD on specified data sources.

Payload parameters

Response parameters

Request example: Run SDD on a single data source

This request runs SDD on the data source Public Case.

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

Payload example

{
  "sources": [
    "Insurance Data"
  ]
}

Response example

{
  "Insurance Data": {
    "id": "d2edc1d0-328c-11ec-9d5a-6793988ccf95",
    "state": "completed",
    "output": {
      "diff": {
        "addedTags": {
          "ssn": [
            "Discovered.PII"
          ],
          "email": [
            "Discovered.PII"
          ]
        },
        "removedTags": {
          "ssn": [
            "Discovered.Country.US"
          ]
        }
      },
      "sddTagResult": {
        "ssn": [
          "Discovered.Entity.Social Security Number",
          "Discovered.Identifier Direct",
          "Discovered.PHI",
          "Discovered.PII"
        ],
        "email": [
          "Discovered.Entity.Electronic Mail Address",
          "Discovered.Identifier Direct",
          "Discovered.PHI",
          "Discovered.PII"
        ]
      }
    }
  }
}

Request example: Run SDD on all data sources

This request runs SDD on all your data sources.

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

Payload example

{
  "all": true
}

Response example

{
  "Insurance Data": {
    "id": "d2edc1d0-328c-11ec-9d5a-6793988ccf95",
    "state": "completed",
    "output": {
      "diff": {
        "addedTags": {
          "ssn": [
            "Discovered.PII"
          ],
          "email": [
            "Discovered.PII"
          ]
        },
        "removedTags": {
          "ssn": [
            "Discovered.Country.US"
          ]
        }
      },
      "sddTagResult": {
        "ssn": [
          "Discovered.Entity.Social Security Number",
          "Discovered.Identifier Direct",
          "Discovered.PHI",
          "Discovered.PII"
        ],
        "email": [
          "Discovered.Entity.Electronic Mail Address",
          "Discovered.Identifier Direct",
          "Discovered.PHI",
          "Discovered.PII"
        ]
      }
    }
  }
  "Finance Data": {
    "id": "d2edc1d0-328c-11ec-9d5a-695e896d59s",
    "state": "completed",
    "output": {
      "diff": {
        "addedTags": {
          "ssn": [
            "Discovered.PII"
          ],
          "email": [
            "Discovered.PII"
          ]
        },
        "removedTags": {
          "ssn": [
            "Discovered.Country.US"
          ]
        }
      },
      "sddTagResult": {
        "ssn": [
          "Discovered.Entity.Social Security Number",
          "Discovered.Identifier Direct",
          "Discovered.PHI",
          "Discovered.PII"
        ],
        "email": [
          "Discovered.Entity.Electronic Mail Address",
          "Discovered.Identifier Direct",
          "Discovered.PHI",
          "Discovered.PII"
        ]
      }
    }
  }
}

Request example: Test run SDD on all data sources

This request runs SDD on the Medical Claims data source with the PII_REVISION framework, but will not tag any columns if matches are found.

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

Payload example

{
  "sources": [
    "Medical Claims"
  ],
  "dryRun": true,
  "template": "PII_REVISION"
}

Response example

{
  "Medical Claims": {
    "id": "86fc4f70-380f-11ec-a432-81748c911385",
    "state": "completed",
    "output": {
      "diff": {
        "addedTags": {},
        "removedTags": {
          "dob": [
            "Discovered.Entity.Date",
            "Discovered.Entity.Date of Birth",
            "Discovered.Identifier Indirect",
            "Discovered.PHI",
            "Discovered.PII"
          ],
          "ssn": [
            "Discovered.Country.US",
            "Discovered.Entity.Social Security Number",
            "Discovered.Identifier Direct",
            "Discovered.PHI"
          ],
          "state": [
            "Discovered.Country.US",
            "Discovered.Entity.Location",
            "Discovered.Entity.State",
            "Discovered.Identifier Indirect"
          ],
          "gender": [
            "Discovered.Entity.Gender",
            "Discovered.Identifier Indirect",
            "Discovered.PHI",
            "Discovered.PII"
          ],
          "date_of_service": [
            "Discovered.Entity.Date",
            "Discovered.Identifier Indirect",
            "Discovered.PHI",
            "Discovered.PII"
          ]
        }
      },
      "sddTagResult": {
        "ssn": [
          "Discovered.PII"
        ]
      }
    }
  }
}

Update patterns or identification frameworks

Update a pattern

PUT /sdd/classifier/{classifierName}

Update a pattern. Partial updates are not supported.

Query parameters

Payload parameters

Response parameters

Request example

The following request updates the name and description of the MY_REGEX_PATTERN pattern.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.immuta.com/sdd/classifier/MY_REGEX_PATTERN

Payload example

{
  "name": "REGULAR_EXPRESSIONS",
  "displayName": "Regular Expressions",
  "description": "A pattern example using regex.",
  "type": "regex",
  "config": {
    "regex": "^[A-Z][a-z]+",
    "tags": ["Discovered.regex-example"]
  }
}

Response example

{
  "createdBy": {
    "id": 1,
    "name": "John",
    "email": "john@example.com"
  },
  "name": "REGULAR_EXPRESSIONS",
  "displayName": "Regular Expressions",
  "description": "A pattern example using regex.",
  "type": "regex",
  "config": {
    "tags": [
      "Discovered.regex-example"
    ],
    "regex": "^[A-Z][a-z]+"
  },
  "id": 67,
  "createdAt": "2021-10-14T18:48:56.289Z",
  "updatedAt": "2021-10-19T12:48:56.289Z"
}

Clone an identification framework

POST /sdd/template/{templateName}/clone

Clone an identification framework.

Query parameters

Payload parameters

Response parameters

Request example

This request clones the MY_FIRST_FRAMEWORK identification framework.

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

Payload example

{
  "name": "CLONE_OF_FIRST_FRAMEWORK",
  "displayName": "Clone of My First Framework",
  "description": "This is a clone of my first framework."
}

Response example

{
  "name": "CLONE_OF_FIRST_FRAMEWORK",
  "displayName": "Clone of My First Framework",
  "description": "This is a clone of my first framework.",
  "createdBy": {
    "id": 1,
    "name": "John",
    "email": "john@example.com"
  },
  "id": 4,
  "createdAt": "2021-10-19T16:21:17.660Z",
  "updatedAt": "2021-10-19T16:21:17.660Z",
  "classifiers": [
    {
      "name": "MY_COLUMN_NAME_REGEX_PATTERN",
      "overrides": {}
    },
    {
      "name": "MY_REGEX_PATTERN",
      "overrides": {}
    }
  ]
}

Update an identification framework

PUT /sdd/template/{templateName}

Update an identification framework.

Query parameters

Payload parameters

Response parameters

Request example

The following request updates the name of, description of, and rules in the MY_FIRST_FRAMEWORK identification framework.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://your-immuta-url.immuta.com/sdd/template/MY_FIRST_FRAMEWORK

Payload example

{
  "name": "HEALTH_DATA",
  "displayName": "Health Data",
  "description": "This framework uses the column regex and regex patterns.",
  "classifiers": [
    {
      "name": "MY_COLUMN_NAME_REGEX_PATTERN"
    },
    {
      "name": "REGULAR_EXPRESSION"
    }
  ]
}

Response example

{
  "name": "HEALTH_DATA",
  "displayName": "Health Data",
  "description": "This framework uses the column regex and regex patterns.",
  "createdBy": {
    "id": 1,
    "name": "John",
    "email": "john@example.com"
  },
  "id": 1,
  "createdAt": "2021-10-14T19:12:22.092Z",
  "updatedAt": "2021-10-20T19:12:22.092Z",
  "classifiers": [
    {
      "name": "MY_COLUMN_NAME_REGEX_PATTERN",
      "overrides": {}
    },
    {
      "name": "REGULAR_EXPRESSION",
      "overrides": {}
    }
  ]
}

Delete patterns or identification frameworks

Delete a pattern

DELETE /sdd/classifier/{classifierName}

Delete a pattern.

Query parameters

Response parameters

Request example

The following request deletes the REGULAR_EXPRESSION pattern.

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.immuta.com/sdd/classifier/REGULAR_EXPRESSION

Response example

{
  "createdBy": {
    "id": 1,
    "name": "John",
    "email": "john@example.com"
  },
  "name": "REGULAR_EXPRESSION",
  "displayName": "Regular Expression",
  "description": "This pattern uses regular expression",
  "type": "regex",
  "config": {
    "tags": [
      "Discovered.regex-example"
    ],
    "regex": "^[A-Z][a-z]+"
  },
  "id": 67,
  "createdAt": "2021-10-19T15:54:28.695Z",
  "updatedAt": "2021-10-19T16:00:02.329Z"
}

Delete an identification framework

DELETE /sdd/template/{templateName}

Delete an identification framework.

Query parameters

Response parameters

Request example

The following request deletes the HEALTH_DATA identification framework.

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://your-immuta-url.immuta.com/sdd/template/HEALTH_DATA

Response example

{
  "name": "HEALTH_DATA",
  "displayName": "Health Data",
  "description": "This is a framework for health data.",
  "createdBy": {
    "id": 1,
    "name": "John",
    "email": "john@immuta.com"
  },
  "id": 1,
  "createdAt": "2021-10-19T16:07:39.356Z",
  "updatedAt": "2021-10-19T16:07:39.356Z",
  "classifiers": [
    {
      "name": "MY_COLUMN_NAME_REGEX_PATTERN",
      "overrides": {}
    }
  ]
}

Configure Immuta

Section Contents

Activities and Notifications

Review your notifications

Review your activity notifications

Query parameters

Response parameters

Request example

Response example

Review your unread notifications

Response parameters

Request example

Response example

Fingerprint Service Status

Get the status of the fingerprint service

Response parameters

Request example

Response example

Licenses

Admin workflow

Add an Immuta license key

Query parameters

Response schema

Request example

Request payload example

Response example

View license keys

Get a list of license keys

Response schema

Request example

Response example

Get the status of a license

Response schema

Request example

Response example

Get license usage

Query parameters

Response schema

Request example

Response example

Delete a license key

Query parameters

Response schema

Request example

Response example

Jobs

Get job status and output

Payload parameters

Response parameters

Request example

Payload example

Response example

Search Filters

Search filter workflow

Save a new search filter

Payload parameters

Response parameters

Request example

Payload example

Response example

Search saved search filters

Query parameters

Response parameters

Request example

Response example

Delete a search filter

Query parameters

Response parameters

Request example

Response example

Tags

Tagging workflow

Create a new tag

Payload parameters

Response parameters

Request example

Payload example

Response example

Search across all tags

Query parameters