Manage IAMs | Documentation

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.

Users workflow

Groups workflow

Authenticate with the API workflow

Create a new user

POST /bim/iam/bim/user

Create a new BIM user.

Required Immuta permission: USER_ADMIN

Payload parameters

Attribute

Description

Required

iamid

string The IAM ID.

Yes

userid

string The new user's username.

Yes

password

string The new user's password.

profile

array Information on the new user's name and email.

permissions

Response parameters

Attribute

Description

integer The user ID.

iamid

string The IAM ID.

userid

string The user's username.

bimAuthorizations

array The attributes and groups given to the user's BIM profile.

iamAuthorizations

array The attributes and groups given to the user's external IAM profile.

authorizations

array The user's groups and attributes.

permissions

array The user's permissions.

profile

array Details on the user, including name, email, phone, about, location, organization, position, preferences, externalUserIds, scim, systemGenerated, id, createdAt, and updatedAt values.

lastLogin

timestamp The date the user most recently logged into Immuta.

disabled

boolean If true, the user is disabled.

createdAt

timestamp The date the user was created.

updatedAt

timestamp The date the user was last updated.

newUserLink

string A link for the new user to log in and create a password.

emailFailed

boolean If true, the login email was unable to be sent to the user's provided email address.

emailSent

boolean If true, a login email was sent to the new user.

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

GET

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

POST

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

PUT

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

DELETE

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

PUT

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

PUT

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

PUT

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

POST

/bim/syncUsers

POST

/iam/{iamId}/sync

PUT

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

DELETE

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

POST

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

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

iamid

string The IAM ID.

Yes

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

iamid

string The IAM ID.

Yes

Payload parameters

Attribute

Description

Required

username

string The user's username for the IAM dictated in the request.

Yes

password

string The user's password for the IAM dictated in the request.

Yes

Response parameters

Attribute

Description

authenticated

boolean If true, the user has been successfully authenticated.

token

string The user's access token.

tokenExpiration

timestamp The date the token will expire.

profileId

integer The user ID.

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.

Requirement: USER_ADMIN Immuta permission or it must be your user profile.

Request parameters

Attribute

Description

Required

iamid

string The IAM ID.

Yes

userId

string The user's username.

Yes

Payload parameters

Attribute

Description

Required

iamid

string The IAM ID.

userid

string The user's username.

string The user email.

phone

string The user phone number.

sqlUser

string The user's SQL username.

about

string Details about the user to be displayed on their profile.

location

string The user's location.

organization

string The user's organization.

position

string The user's position.

externalUserIds

array A list of the user's external usernames for hdfsUser, databricksUser, snowflakeUser, prestoUser, asaUser, and redshiftUser.

preferences

array

scim

array

Response parameters

Attribute

Description

profile

array Details information about the user, including name, email, phone, about, location, organization, position, preferences, externalUserIds, scim, id, and the date of creation.

permissions

array A list of the user's permissions.

iamid

string The IAM ID.

userid

string The user's username.

authorizations

array The user's attributes and groups.

updatedAt

timestamp The date the user was last updated.

disabled

boolean If true, the user is disabled.

lastLogin

timestamp The date the user last logged in.

bimAuthorizations

array The attributes and groups given to the user's BIM profile.

iamAuthorizations

array The attributes and groups given to the user's external IAM profile.

hasLogin

boolean If true, the user has logged into Immuta.

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.

Required Immuta permission: USER_ADMIN

Request parameters

Attribute

Description

Required

iamid

string The IAM ID.

Yes

userid

string The user's username.

Yes

permission

Yes

Response parameters

Attribute

Description

integer The user's ID.

iamid

string The IAM ID.

userid

string The user's username.

bimAuthorizations

array The attributes and groups given to the user's BIM profile.

iamAuthorizations

array The attributes and groups given to the user's external IAM profile.

authorizations

array Details on the user's groups and attributes.

permissions

array[string] A list of the user's permissions.

profile

integer The user's profile ID.

lastLogin

timestamp The date the user last logged into Immuta.

disabled

boolean If true, the user is disabled.

createdAt

timestamp The date the user was created.

updatedAt

timestamp The date the user was last updated.

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.

Required Immuta permission: USER_ADMIN

Request parameters

Attribute

Description

Required

iamid

string The IAM ID.

Yes

userid

string The user's username.

Yes

Request parameters

Attribute

Description

Required

permissions

Yes

Response parameters

Attribute

Description

integer The user's ID.

iamid

string The IAM ID.

userid

string The user's username.

bimAuthorizations

array The attributes and groups given to the user's BIM profile.

iamAuthorizations

array The attributes and groups given to the user's external IAM profile.

authorizations

array Details on the user's groups and attributes.

permissions

array A list of the user's permissions.

profile

integer The user's profile ID.

lastLogin

timestamp The date the user last logged into Immuta.

disabled

boolean If true, the user is disabled.

createdAt

timestamp The date the user was created.

updatedAt

timestamp The date the user was last updated.

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.

Requirement: USER_ADMIN Immuta permission or it must be your profile.

Request parameters

Attribute

Description

Required

iamid

string The IAM ID.

Yes

userid

string The user's username.

Yes

Request parameters

Attribute

Description

Required

originalPassword

string The user's old password.

Yes

password

string The user's new password.

Yes

Response parameters

Attribute

Description

success

boolean If true, the user's password has been successfully changed to the new password.

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.

Required Immuta permission: USER_ADMIN

Request parameters

Attribute

Description

Required

iamid

string The IAM ID.

Yes

userid

string The user's username.

Yes

disable

boolean If true, the user will be disabled.

Yes

Response parameters

Attribute

Description

userid

string The user's username.

disabled

boolean If true, the user is disabled.

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.

Required Immuta permission: USER_ADMIN

Payload parameters

Attribute

Description

Required

iamid

string The external IAM ID.

Yes

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.

Required Immuta permission: USER_ADMIN

Request parameters

Attribute

Description

Required

iamId

string The external IAM ID.

Yes

Payload parameters

Attribute

Description

Required

dryRun

boolean If true, no updates will actually be made.

Yes

iamConfig

array Details about the IAM configuration, including authenticationOnly, credentials, defaultPermissions, displayName, id, ldapSync, and options.

plugin

string The type of plugin the IAM uses, ldap.

schema

array Details about the IAM schema, including group, profile, authorizations, and externalUserIds.

supportedActions

string

type