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 string
The new user's username.
string
The new user's password.
array
Information on the new user's name and email.
array
Information on the new user's permissions.
Response parameters
Attribute Description string
The user's username.
array
The attributes and groups given to the user's BIM profile.
array
The attributes and groups given to the user's external IAM profile.
array
The user's groups and attributes.
array
The user's permissions.
array
Details on the user, including name
, email
, phone
, about
, location
, organization
, position
, preferences
, externalUserIds
, scim
, systemGenerated
, id
, createdAt
, and updatedAt
values.
timestamp
The date the user most recently logged into Immuta.
boolean
If true
, the user is disabled.
timestamp
The date the user was created.
timestamp
The date the user was last updated.
string
A link for the new user to log in and create a password.
boolean
If true
, the login email was unable to be sent to the user's provided email address.
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
.
Copy 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
Copy {
"iamid" : "bim" ,
"userid" : "charlie.doe@immuta.com" ,
"profile" : {
"name" : "Charlie Doe" ,
"email" : "charlie.doe@immuta.com"
} ,
"permissions" : []
}
Response example
Copy {
"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 /bim/iam/{iamid}/user/authenticate
/bim/iam/{iamid}/user/authenticate
/bim/iam/{iamid}/user/{userid}/profile
/bim/iam/{iamid}/user/{userid}/permissions/{permission}
/bim/iam/{iamid}/user/{userid}/permissions
/bim/iam/{iamid}/user/{userid}/password
/bim/iam/{iamid}/user/{userid}/disable/{disable}
/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue}
/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value}
/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
Attribute Description Required
Request example
This example request
Copy curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
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
Payload parameters
Attribute Description Required string
The user's username for the IAM dictated in the request.
string
The user's password for the IAM dictated in the request.
Response parameters
Attribute Description boolean
If true
, the user has been successfully authenticated.
string
The user's access token.
timestamp
The date the token will expire.
Request example
This example request with the payload below will authenticate the user using the bim
IAM.
Copy curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/iam/bim/user/authenticate
Payload example
Copy {
"username" : "demo.user@immuta.com" ,
"password" : "********"
}
Response example
Copy {
"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 string
The user's username.
Payload parameters
Attribute Description Required string
The user's username.
string
The user phone number.
string
The user's SQL username.
string
Details about the user to be displayed on their profile.
string
The user's location.
string
The user's organization.
string
The user's position.
array
A list of the user's external usernames for hdfsUser
, databricksUser
, snowflakeUser
, prestoUser
, asaUser
, redshiftUser
, and teradataUser
.
Response parameters
Attribute Description array
Details information about the user, including name
, email
, phone
, about
, location
, organization
, position
, preferences
, externalUserIds
, scim
, id
, and the date of creation.
array
A list of the user's permissions.
string
The user's username.
array
The user's attributes and groups.
timestamp
The date the user was last updated.
boolean
If true
, the user is disabled.
timestamp
The date the user last logged in.
array
The attributes and groups given to the user's BIM profile.
array
The attributes and groups given to the user's external IAM profile.
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
.
Copy 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
Copy {
"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
Copy {
"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 string
The user's username.
Response parameters
Attribute Description string
The user's username.
array
The attributes and groups given to the user's BIM profile.
array
The attributes and groups given to the user's external IAM profile.
array
Details on the user's groups and attributes.
array[string]
A list of the user's permissions.
integer
The user's profile ID.
timestamp
The date the user last logged into Immuta.
boolean
If true
, the user is disabled.
timestamp
The date the user was created.
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
.
Copy 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
Copy {
"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 string
The user's username.
Request parameters
Attribute Description Required 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.
Response parameters
Attribute Description string
The user's username.
array
The attributes and groups given to the user's BIM profile.
array
The attributes and groups given to the user's external IAM profile.
array
Details on the user's groups and attributes.
array
A list of the user's permissions.
integer
The user's profile ID.
timestamp
The date the user last logged into Immuta.
boolean
If true
, the user is disabled.
timestamp
The date the user was created.
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
.
Copy 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
Copy [
"CREATE_DATA_SOURCE_IN_PROJECT" , "CREATE_PROJECT" , "CREATE_DATA_SOURCE"
]
Response example
Copy {
"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 string
The user's username.
Request parameters
Attribute Description Required string
The user's old password.
string
The user's new password.
Response parameters
Attribute Description 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
.
Copy 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
Copy {
"originalPassword" : "old********" ,
"password" : "new********"
}
Response example
Disable or enable a user
PUT
/bim/iam/{iamid}/user/{userid}/disable/{disable}
Disable / enable the specified BIM user.
Request parameters
Attribute Description Required string
The user's username.
boolean
If true
, the user will be disabled.
Response parameters
Attribute Description string
The user's username.
boolean
If true
, the user is disabled.
Request example
This example request will disabled the user with the username jane.doe@immuta.com
.
Copy 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
Copy {
"userid" : "jane.doe@immuta.com" ,
"disabled" : true
}
Sync users from an external IAM
POST
/bim/syncUsers
Sync users from an external IAM.
Payload parameters
Attribute Description Required string
The external IAM ID.
Request example
This example request will sync the users from the specified external IAM with Immuta.
Copy curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/syncUsers
Payload example
Sync LDAP users with Immuta
POST
/iam/{iamId}/sync
Sync LDAP users with Immuta.
Request parameters
Attribute Description Required string
The external IAM ID.
Payload parameters
Attribute Description Required boolean
If true
, no updates will actually be made.
array
Details about the IAM configuration, including authenticationOnly
, credentials
, defaultPermissions
, displayName
, id
, ldapSync
, and options
.
string
The type of plugin the IAM uses, ldap
.
array
Details about the IAM schema, including group
, profile
, authorizations
, and externalUserIds
.
string
The type of IAM, ldap
.
Response parameters
Attribute Description integer
The total number of users in the external IAM that could be synced over into Immuta.
array
Details about the users who were successfully imported from the sync, including userId
and dn
.
array
Details about the users who were successfully refreshed from the sync, including userId
and dn
.
array
Details about the users who were successfully disabled from the sync, including userId
and dn
.
array
Details about the users who were successfully enabled from the sync, including userId
and dn
.
boolean
If true
, the sync created a job to run in the background.
integer
The number of users successfully updated from the IAM.
Request example
This example request will sync the users from Jump Cloud with Immuta.
Copy 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
Copy {
"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
Copy {
"totalCount" : 10 ,
"importedUsers" : [{
"userId" : "user-1@example.com" ,
"dn" : "uid=user-1,ou=Users,o=redacted,dc=jumpcloud,dc=com"
} , {
"userId" : "user-2@example.com" ,
"dn" : "uid=user-2,ou=Users,o=redacted,dc=jumpcloud,dc=com"
} , {
"userId" : "user-3@example.com" ,
"dn" : "uid=user-3,ou=Users,o=redacted,dc=jumpcloud,dc=com"
} , {
"userId" : "user-4@example.com" ,
"dn" : "uid=user-4,ou=Users,o=redacted,dc=jumpcloud,dc=com"
} , {
"userId" : "user-5@example.com" ,
"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 string
The type of model the attribute is added to. Options include group
or user
.
string
The user or group ID.
string
The attribute name.
string
The attribute value.
Response parameters
Attribute Description integer
The user or group ID.
string
The user's username.
array
The attributes and groups given to the user's BIM profile.
array
The attributes and groups given to the user's external IAM profile.
array
Details on the user's or group's and attributes.
array
A list of the user's permissions.
integer
The user's profile ID.
timestamp
The date the user last logged into Immuta.
boolean
If true
, the user is disabled.
timestamp
The date the user was created.
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
.
Copy curl \
--request PUT \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/jane.doe@immuta.com/authorizations/Finance/Red%20Team
Response example