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
Response parameters
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
Authenticate a user from an outside IAM
GET
/bim/iam/{iamid}/user/authenticate
Authenticate a user from a 3rd-party identity provider.
Request parameters
Request example
This example request
Copy 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
Payload parameters
Response parameters
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" \
--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
Payload parameters
Response parameters
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
Response parameters
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
Request parameters
Response parameters
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
Request parameters
Response parameters
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
Response parameters
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
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
Payload parameters
Response parameters
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
Response parameters
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
Copy {
"id" : 16 ,
"iamid" : "bim" ,
"userid" : "jane.doe@immuta.com" ,
"bimAuthorizations" : {
"Finance" : [ "CFA" , "Red Team" ]
} ,
"iamAuthorizations" : null ,
"authorizations" : {
"Finance" : [ "CFA" , "Red Team" ]
} ,
"permissions" : [ "CREATE_DATA_SOURCE_IN_PROJECT" , "CREATE_PROJECT" ] ,
"profile" : 16 ,
"authentication" : 5 ,
"systemGenerated" : false ,
"lastLogin" : "2021-10-07T02:58:31.708Z" ,
"lastExternalRefresh" : "2021-10-07T02:58:31.708Z" ,
"disabled" : false ,
"createdAt" : "2021-10-06T22:17:46.500Z" ,
"updatedAt" : "2021-10-18T17:09:53.711Z"
}
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.
Request parameters
Response parameters
Request example
This example request will remove the attribute Country.JP
from the user with the user ID jane.doe@immuta.com
.
Copy curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/iam/bim/user/jane.doe@demo.com/authorizations/Country/JP
Response example
Copy {
"id" : 4 ,
"iamid" : "bim" ,
"userid" : "jane.doe@demo.com" ,
"bimAuthorizations" : {
"Country" : [ "US" ] ,
"Environment" : [ "Dev" ] ,
"OfficeLocation" : [ "Japan" ]
} ,
"iamAuthorizations" : null ,
"authorizations" : {
"Country" : [ "US" ] ,
"Environment" : [ "Dev" ] ,
"OfficeLocation" : [ "Japan" ]
} ,
"permissions" : [ "CREATE_DATA_SOURCE_IN_PROJECT" , "CREATE_PROJECT" , "USER_ADMIN" , "GOVERNANCE" ] ,
"profile" : 4 ,
"authentication" : 3 ,
"systemGenerated" : false ,
"lastLogin" : "2022-08-11T01:36:01.947Z" ,
"lastExternalRefresh" : "2022-08-11T01:36:01.947Z" ,
"disabled" : false ,
"createdAt" : "2022-06-02T17:37:24.515Z" ,
"updatedAt" : "2022-08-11T18:40:51.366Z"
}
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.
Request parameters
Payload parameters
Response parameters
Request example
This example request will clone the user with the username jane.doe@immuta.com
.
Copy curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/jane.doe%40demo.com/clone
Payload example
Copy [
"john.doe@demo.com"
]
Response example
Copy {
"failedEmails" : []
}
Review user information
Search all IAMs
GET
/bim/iam
Get a listing of configured IAM services.
Response parameters
Request example
The request below will list all of the IAMs in use.
Copy curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam
Response example
Copy [
{
"id" : "bim" ,
"displayName" : "Immuta" ,
"type" : "built-in" ,
"oauth" : false
} ,
{
"id" : "oktaSamlIAM" ,
"displayName" : "Okta SAML" ,
"type" : "saml" ,
"oauth" : false
} ,
{
"id" : "ldap" ,
"displayName" : "LDAP" ,
"type" : "ldap"
}
]
Search all users
GET
/bim/user
Administrative search over the aggregated view of all users.
Query parameters
Response parameters
Request example
The request below will search all of the users in Immuta.
Copy curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/user?size= 25 & name = bar & sortOrder = asc
Response example
Copy {
"count" : "2" ,
"hits" : [
{
"id" : 18 ,
"iamid" : "bim" ,
"userid" : "bspringer@immuta.com" ,
"permissions" : [
"CREATE_DATA_SOURCE" ,
"CREATE_PROJECT"
] ,
"profile" : {
"name" : "Barrett Springer" ,
"email" : "bspringer@immuta.com" ,
"id" : 18 ,
"createdAt" : "2018-07-05T07:37:06.569Z" ,
"updatedAt" : "2018-07-05T07:37:06.569Z"
} ,
"authentication" : 18 ,
"systemGenerated" : false ,
"lastLogin" : "2018-07-05T07:39:56.365Z" ,
"disabled" : false ,
"createdAt" : "2018-07-05T07:37:05.987Z" ,
"updatedAt" : "2018-07-05T07:37:05.987Z"
} ,
{
"id" : 5 ,