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

1. Create a new user.

2. Manage your users.

3. Review your users' information.

4. Delete a user.

Groups workflow

1. Create a new group.

2. Manage groups.

3. Search groups.

4. Delete a group.

Authenticate with the API workflow

1. Create an API Key.

2. Authenticate with an API key.

3. View tokens and API key information.

4. Remove an API key.

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 [e-mail].

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": "[e-mail]",
  "profile": {
    "name": "Charlie Doe",
    "email": "[e-mail]"
  },
  "permissions": []
}

Response example

{
  "newUser": {
    "id": 18,
    "iamid": "bim",
    "userid": "[e-mail]",
    "bimAuthorizations": null,
    "iamAuthorizations": null,
    "authorizations": {},
    "permissions": ["CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT"],
    "profile": {
      "name": "Charlie Doe",
      "email": "[e-mail]",
      "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	Authenticate a user from a 3rd party identity provider.
POST	/bim/iam/{iamid}/user/authenticate	Authenticate a user using their username and password and proxying it to the specified IAM service.
PUT	/bim/iam/{iamid}/user/{userid}/profile	Update a specified user's profile.
DELETE	/bim/iam/{iamid}/user/{userid}/permissions/{permission}	Remove the specified user's permission.
PUT	/bim/iam/{iamid}/user/{userid}/permissions	Update the specified user's permissions.
PUT	/bim/iam/{iamid}/user/{userid}/password	Update the specified user's password.
PUT	/bim/iam/{iamid}/user/{userid}/disable/{disable}	Disable / enable the specified BIM user.
POST	/bim/syncUsers	Sync Users for external IAM.
POST	/iam/{iamId}/sync	Sync LDAP users with Immuta.
PUT	/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue}	Update the specified user's attributes.
DELETE	/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value}	Remove an attribute from the specified group or user.
POST	/bim/iam/bim/user/{userid}/clone	Clones the provided user to create multiple additional user accounts.

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": "[e-mail]",
  "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 [e-mail].

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/[e-mail]/profile

Payload example

{
  "email": "[e-mail]",
  "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": "[e-mail]"
}

Response example

{
  "name": "Jane Doe",
  "email": "[e-mail]",
  "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 [e-mail].

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": "[e-mail]",
  "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 [e-mail] 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": "[e-mail]",
  "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 [e-mail].

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
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 [e-mail].

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": "[e-mail]",
  "disabled": true
}

Sync users from an external IAM

POST /bim/syncUsers

Sync users from an external IAM.

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.

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.	No
plugin	string The type of plugin the IAM uses, ldap.	No
schema	array Details about the IAM schema, including group, profile, authorizations, and externalUserIds.	No
supportedActions	string	No
type	string The type of IAM, ldap.	No

Response parameters

Attribute	Description
totalCount	integer The total number of users in the external IAM that could be synced over into Immuta.
importedUsers	array Details about the users who were successfully imported from the sync, including userId and dn.
refreshedUsers	array Details about the users who were successfully refreshed from the sync, including userId and dn.
disabledUsers	array Details about the users who were successfully disabled from the sync, including userId and dn.
enabledUsers	array Details about the users who were successfully enabled from the sync, including userId and dn.
runningInBackground	boolean If true, the sync created a job to run in the background.
count	integer The number of users successfully updated from the IAM.

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": "[e-mail]",
    "dn": "uid=user-1,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "[e-mail]",
    "dn": "uid=user-2,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "[e-mail]",
    "dn": "uid=user-3,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "[e-mail]",
    "dn": "uid=user-4,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "[e-mail]",
    "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
iamid	string The IAM ID.	Yes
modelType	string The type of model the attribute is added to. Options include group or user.	Yes
modelID	string The user or group ID.	Yes
attributeName	string The attribute name.	Yes
attributeValue	string The attribute value.	Yes

Response parameters

Attribute	Description
id	integer The user or group ID.
iamid	string The IAM ID.
userid	string The user's username.
name	string The group name.
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 or group's 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 will add the attribute Finance.Red Team to the user with the username [e-mail].

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

Response example

{
  "id": 16,
  "iamid": "bim",
  "userid": "[e-mail]",
  "bimAuthorizations": {
    "Finance": ["CFA", "Red Team"]
  },
  "iamAuthorizations": null,
  "authorizations": {
    "Finance": ["CFA", "Red Team"]
  },
  "permissions": ["CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT"],
  "profile": 16,
  "authentication": 5,