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
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
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
.
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
Authenticate a user from an outside IAM
GET
/bim/iam/{iamid}/user/authenticate
Authenticate a user from a 3rd-party identity provider.
Request parameters
iamid
string
The IAM ID.
Yes
Request example
This example request
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.
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.
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
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
.
Response example
Update a user's permissions
PUT
/bim/iam/{iamid}/user/{userid}/permissions
Update the specified user's permission.
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
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
.
Payload example
Response example
Update a user's password
PUT
/bim/iam/{iamid}/user/{userid}/password
Update the specified user's password.
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.
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 disabled 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.
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.
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
string
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.
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
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 jane.doe@immuta.com
.