Manage IAMs
Understand the parameters and response schema of the bim endpoints
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.
Create a new user
POST /bim/iam/bim/user
Create a new BIM user.
Required Immuta permission: USER_ADMIN
Payload parameters
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. See Immuta permissions and personas for a list of Immuta permissions.
No
type
string The type of new identity to create. Options include user and agent.
No
Response parameters
Returns an object containing newUser (detailed user object), newUserLink, emailFailed, and emailSent.
Request example
This example request with the payload below will create a new BIM user with the username charlie.doe@immuta.com.
Payload example
Response example
Manage users
POST
/bim/iam/{iamid}/user/authenticate
DELETE
/bim/iam/{iamid}/user/{userid}/permissions/{permission}
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
DELETE
/bim/iam/{iamid}/authorizations/{key}/{value}
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
iamid
string The IAM ID.
Yes
Payload parameters
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
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.
Payload example
Response example
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
iamid
string The IAM ID.
Yes
userid
string The user's username.
Yes
Payload parameters
iamid
string The IAM ID.
No
userid
string The user's username.
No
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
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.
Payload example
Response example
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
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
Returns the updated user object.
Request example
This example request will delete the permission CREATE_PROJECT from the user with the username john.doe@immuta.com.
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
iamid
string The IAM ID.
Yes
userid
string The user's username.
Yes
Request parameters
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
Returns the updated user object.
Request example
This example request with the payload below will change the permissions of the user with the username charlie.doe@immuta.com to CREATE_PROJECT and CREATE_DATA_SOURCE.
Payload example
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
iamid
string The IAM ID.
Yes
userid
string The user's username.
Yes
Request parameters
originalPassword
string The user's old password.
Yes
password
string The user's new password.
Yes
Response parameters
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.
Payload example
Response example
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
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
userid
string The user's username.
disabled
boolean If true, the user is disabled.
Request example
This example request will disable the user with the username jane.doe@immuta.com.
Response example
Sync users from an external IAM
POST /bim/syncUsers
Sync users from an external IAM.
Required Immuta permission: USER_ADMIN
Payload parameters
iamid
string The external IAM ID.
Yes
Request example
This example request will sync the users from the specified external IAM with Immuta.
Payload example
Sync LDAP users with Immuta
POST /iam/{iamId}/sync
Sync LDAP users with Immuta.
Required Immuta permission: USER_ADMIN
Request parameters
iamId
string The external IAM ID.
Yes
Payload parameters
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
array The set of actions that this IAM integration supports to determine which sync or management operations Immuta is allowed to execute for this IAM.
No
type
string The type of IAM, ldap.
No
Response parameters
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.
Payload example
Response example
Update a user's or group's attributes
PUT /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue}
Update the specified user's attributes.
Required Immuta permission: USER_ADMIN
Request parameters
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
Returns the updated user or group object.
Request example
This example request will add the attribute Finance.Red Team to the user with the username jane.doe@immuta.com.
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.
Required Immuta permission: USER_ADMIN
Request parameters
iamid
string The ID for the IAM the user or group is under.
Yes
modelId
string The user or group ID.
Yes
modelType
string The type of model the attribute is being removed from. Options include group or user.
Yes
key
string The attribute to remove.
Yes
value
string The attribute value to remove.
No
Response parameters
Returns the updated user or group object.
Request example
This example request will remove the attribute Country.JP from the user with the user ID jane.doe@immuta.com.
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.
Required Immuta permission: USER_ADMIN
Request parameters
userid
string The user's username.
Yes
Payload parameters
array The list of new users' emails.
Yes
Response parameters
failedEmails
array A list of any emails that failed to become users.
Request example
This example request will clone the user with the username jane.doe@immuta.com.
Payload example
Response example
Remove the specified attribute from all users
DELETE /bim/iam/{iamid}/authorizations/{key}/{value}
Removes the specified authorization from all groups and users.
Required Immuta permission: USER_ADMIN
Request parameters
iamid
string The ID for the IAM the attribute is in. Use bim for Immuta attributes.
Yes
key
string The attribute key to remove.
Yes
value
string The attribute value to remove.
No
Response parameters
None
Request example
This example request will delete the attribute attr.new from all users and groups in Immuta.
Review user information
Search all IAMs
GET /bim/iam
Get a listing of configured IAM services.
Response parameters
id
string The IAM ID.
displayName
string The name displayed in Immuta and entered at the time of configuration.
type
string The identity provider type.
oauth
boolean When true, the IAM service uses OAuth framework for authorization.
Request example
The request below will list all of the IAMs in use.
Response example
Search all users
GET /bim/user
Search all users.
Query parameters
size
integer The maximum number of records to return. The default is 25.
No
name
string A partial name to match against user names.
No
userid
string A partial ID to match against user IDs.
No
string A partial email address to match against user email addresses.
No
iamid
string[] Optionally provide the IAM to filter the users.
No
profileIds
string[] Filters results to return users with the specified profile IDs.
No
excludeSystemGenerated
boolean If true, the results will exclude accounts automatically created by Immuta.
No
excludeAdminAndGovernor
boolean If true, users with the admin and governor permissions will be excluded.
No
excludeDeletediams
boolean If true, the results will exclude users for any IAMs that are no longer configured.
No
excludebim
boolean If true, users from the Immuta internal identity manager will be excluded.
No
includeDisabled
boolean If true, the results will include disabled users.
No
offset
integer Offset to start returning values.
No
sortField
string The field to sort results on. The default is user name. Possible values: name, createdAt, iamid, email.
No
sortOrder
string The order that the results will be sorted in. The default is asc. Possible values: asc, desc.
No
permission
string A permission to filter the users by.
No
Response parameters
Returns a list of detailed user objects.
Request example
The request below will search all of the users in Immuta.
View current user's information
GET /bim/rpc/user/current
Get the currently logged in user's information.
Response parameters
Returns a detailed user object.
Request example
This request will return information on the user that is logged in.
Response example
View a user's information
GET /bim/iam/{iamid}/user/{id}
Gets the specified user's aggregated view.
Required Immuta permission: USER_ADMIN or AUDIT
Request parameters
iamid
string The IAM ID.
Yes
id
integer The user ID.
Yes
params
query
No
Response parameters
profile
array Details about the user, including name, email, phone, about, location, organization, position, preferences, externalUserIds, scim, id, and the date of creation.
preferences
array Information about the user's tabDataSourceState, tabProjectState, sortDataSourceState, and currentProject.
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.
systemGenerated
boolean
disabled
boolean If true, the user is disabled.
lastLogin
timestamp The date the user last logged in.
lastExternalRefresh
timestamp
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 return information about the user with the ID 2.
Response example
View a user profile
GET /bim/iam/{iamid}/user/{userid}/profile
Gets the specified user's profile.
Request parameters
iamid
string The IAM ID.
Yes
userid
integer The user ID.
Yes
Response parameters
name
string The user's name.
string The user's email.
phone
string The user's phone number.
about
string Details about the user.
location
string The user's location.
organization
string The user's organization.
position
string The user's position.
externalUserIds
array A list of user IDs for technologies outside of Immuta, if specified as different from the Immuta user ID.
createdAt
timestamp The date the user was created.
updatedAt
timestamp The date the profile was last updated.
preferences
array Information on the user's preferences including values for sortProjectState and currentProject.
Request example
This example request will return the profile of the user with the ID 2.
Response example
View a user's groups
GET /bim/iam/{iamid}/user/{userid}/groups
Get the specified user's list of groups.
Required Immuta permission: USER_ADMIN
Request parameters
iamid
string The IAM ID.
Yes
userid
string The user's username.
Yes
Response parameters
id
integer The group ID.
name
string The group name.
iamid
string The IAM ID.
groupUser
integer The user's unique membership group ID.
Request example
This example request will return information on the groups of the user with the username john.doe@immuta.com.
Response example
Search all users by details
POST /bim/user/search
Administrative search over the aggregated view of all users based on specific user details.
Required Immuta permission: USER_ADMIN
Payload parameters
size
integer The maximum number of records to return. The default is 25.
No
name
string A partial name to match against user names.
No
string A partial email address to match against user email addresses.
No
userid
string A partial ID to match against user IDs.
No
iamid
array[string] Optionally provide the IAM to filter the users.
No
excludeSystemGenerated
boolean If true, the results will exclude accounts automatically created by Immuta.
No
excludeAdminAndGovernor
boolean If true, users with the admin and governor permissions will be excluded.
No
excludeDeletedIams
boolean If true, the results will exclude users for any IAMs that are no longer configured.
No
excludeBIM
boolean If true, users from the Immuta internal identity manager will be excluded.
No
includeDisabled
boolean If true, the results will include disabled users.
No
includeEnabled
boolean If true, the results will include enabled users.
No
sortField
string The field to sort results on. The default is name. Possible values: name, createdAt, iamid, email.
No
sortOrder
string The order that the results will be sorted in. The default is asc. Possible values: asc, desc.
No
offset
integer Offset to start returning values.
No
permission
string A permission to filter the users by.
No
domainPermission
string A domain permission to filter the users by.
No
domainId
string A domain ID to filter the users by.
No
profileIds
array[integer] Filters results to return users with the specified profile IDs.
No
globalUserIds
array[string] Filters results to return users with the specified global user IDs.
No
groupNames
array[string] Filters results to return users that belong to the specified groups by name.
No
groupIds
array[integer] Filters results to return users that belong to the specified groups by ID.
No
userAttributes
array[object] Filters results to return users with the specified attributes. Each object should contain key and value properties.
No
Response parameters
Returns a list of user objects.
Request example
This example request will return information on the users with "arthur" in their name.
Payload example
Create a new group
POST /bim/group
Create a new group.
Required Immuta permission: USER_ADMIN
Payload parameters
iamid
string The IAM ID.
Yes
name
string The new group name.
Yes
string The new group's email.
No
description