Manage IAMs

BIM API reference guide

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.

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.

No

profile

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

No

permissions

array Information on the new user's permissions.

No

Response parameters

Attribute
Description

id

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

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}

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.

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.

No

userid

string The user's username.

No

email

string The user email.

No

phone

string The user phone number.

No

sqlUser

string The user's SQL username.

No

about

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

No

location

string The user's location.

No

organization

string The user's organization.

No

position

string The user's position.

No

externalUserIds

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

No

preferences

array

No

scim

array

No

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.

Request parameters

Attribute
Description
Required

iamid

string The IAM ID.

Yes

userid

string The user's username.

Yes

permission

string The permission to remove. See Immuta permissions and personas for a list of Immuta permissions.

Yes

Response parameters

Attribute
Description

id

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.

Request parameters

Attribute
Description
Required

iamid

string The IAM ID.

Yes

userid

string The user's username.

Yes

Request parameters

Attribute
Description
Required

permissions

array[string] A list of the user's permissions. This list is going to be a comprehensive list of all of the user's permissions. See Immuta permissions and personas for a list of Immuta permissions.

Yes

Response parameters

Attribute
Description

id

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.

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.