Manage IAMs
BIM API reference guide
Last updated
Was this helpful?
BIM API reference guide
Last updated
Was this helpful?
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.
Because the BIM endpoint encompasses groups, users, and authentications, there are three workflows.
.
.
.
.
.
.
.
.
POST
/bim/iam/bim/user
Create a new BIM user.
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
No
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.
This example request with the payload below will create a new BIM user with the username charlie.doe@immuta.com
.
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
GET
/bim/iam/{iamid}/user/authenticate
Authenticate a user from a 3rd-party identity provider.
iamid
string
The IAM ID.
Yes
This example request
POST
/bim/iam/{iamid}/user/authenticate
Authenticate a user using their username and password and proxying it to the specified IAM service.
iamid
string
The IAM ID.
Yes
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
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.
This example request with the payload below will authenticate the user using the bim
IAM.
Payload example
PUT
/bim/iam/{iamid}/user/{userid}/profile
Update a specified user's profile.
iamid
string
The IAM ID.
Yes
userId
string
The user's username.
Yes
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
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.
This example request will change the location to Boston, MA
for the user with the username jane.doe@immuta.com
.
Payload example
DELETE
/bim/iam/{iamid}/user/{userid}/permissions/{permission}
Remove the specified user's permission.
iamid
string
The IAM ID.
Yes
userid
string
The user's username.
Yes
permission
Yes
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.
This example request will delete the permission CREATE_DATA_SOURCE_IN_PROJECT
from the user with the username john.doe@immuta.com
.
PUT
/bim/iam/{iamid}/user/{userid}/permissions
Update the specified user's permission.
iamid
string
The IAM ID.
Yes
userid
string
The user's username.
Yes
permissions
Yes
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.
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
PUT
/bim/iam/{iamid}/user/{userid}/password
Update the specified user's password.
iamid
string
The IAM ID.
Yes
userid
string
The user's username.
Yes
originalPassword
string
The user's old password.
Yes
password
string
The user's new password.
Yes
success
boolean
If true
, the user's password has been successfully changed to the new password.
This example request with the payload below will change the password of the user with the ID jane.doe@immuta.com
.
Payload example
PUT
/bim/iam/{iamid}/user/{userid}/disable/{disable}
Disable / enable the specified BIM user.
iamid
string
The IAM ID.
Yes
userid
string
The user's username.
Yes
disable
boolean
If true
, the user will be disabled.
Yes
userid
string
The user's username.
disabled
boolean
If true
, the user is disabled.
This example request will disabled the user with the username jane.doe@immuta.com
.
POST
/bim/syncUsers
Sync users from an external IAM.
iamid
string
The external IAM ID.
Yes
This example request will sync the users from the specified external IAM with Immuta.
Payload example
POST
/iam/{iamId}/sync
Sync LDAP users with Immuta.
iamId
string
The external IAM ID.
Yes
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
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.
This example request will sync the users from Jump Cloud with Immuta.
Payload example
PUT
/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue}
Update the specified user's attributes.
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
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.
This example request will add the attribute Finance.Red Team
to the user with the username jane.doe@immuta.com
.
DELETE
/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value}
Remove an attribute from the specified group or user.
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
id
integer
The user or group ID.
iamid
string
The IAM ID.
authorizations
array
The user or group attributes after the request has been made.
permissions
array
The user or group permissions.
profile
integer
The profile ID, if the model is a user.
systemGenerated
boolean
If true
, the user was created by Immuta.
createdAt
timestamp
The date the user or group was created.
updatedAt
timestamp
The date the user or group was last updated.
This example request will remove the attribute Country.JP
from the user with the user ID jane.doe@immuta.com
.
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.
userId
string
The user's username.
Yes
array
The list of new users' emails.
Yes
failedEmails
array
A list of any emails that failed to become users.
This example request will clone the user with the username jane.doe@immuta.com
.
GET
/bim/iam
GET
/bim/user
GET
/bim/rpc/user/current
GET
/bim/iam/{iamid}/user/{id}
GET
/bim/iam/{iamid}/user/{userid}/profile
GET
/bim/iam/{iamid}/user/{userid}/groups
GET
/bim/iam
Get a listing of configured IAM services.
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.
The request below will list all of the IAMs in use.
GET
/bim/user
Administrative search over the aggregated view of all users.
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.