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" \
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" \
--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
, and redshiftUser
.
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
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
Attribute Description Required string
The ID for the IAM the user or group is under.
string
The user or group ID.
string
The type of model the attribute is being removed from. Options include group
or user
.
string
The attribute to remove.
string
The attribute value to remove.
Response parameters
Attribute Description integer
The user or group ID.
array
The user or group attributes after the request has been made.
array
The user or group permissions.
integer
The profile ID, if the model is a user.
boolean
If true
, the user was created by Immuta.
timestamp
The date the user or group was created.
timestamp
The date the user or group was last updated.
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
Attribute Description Required string
The user's username.
Payload parameters
Attribute Description Required array
The list of new users' emails.
Response parameters
Attribute Description 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
.
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
Method Path Purpose /bim/iam/{iamid}/user/{id}
/bim/iam/{iamid}/user/{userid}/profile
/bim/iam/{iamid}/user/{userid}/groups
Search all IAMs
GET
/bim/iam
Get a listing of configured IAM services.
Response parameters
Attribute Description string
The name displayed in Immuta and entered at the time of configuration.
string
The identity provider type.
boolean
When true
, the IAM service uses OAuth framework for authorization.
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
Attribute Description Required integer
The maximum number of records to return. The default is 25
.
string
A partial name to match against user names.
string
A partial ID to match against user IDs.
string
A partial email address to match against user email addresses.
string[]
Optionally provide the IAM to filter the users.
string[]
Filters results to return users with the specified profile IDs.
boolean
If true
, the results will exclude accounts automatically created for handlers that periodically crawl and ingest.
boolean
If true
, Admin and Governor accounts will be excluded.
boolean
If true
, the results will exclude users for any IAMs that are no longer configured.
boolean
If true
, users from the Immuta internal identity manager will be excluded.
boolean
If true
, the results will include disabled users.
integer
Offset to start returning values.
string
The field to sort results on. The default is user name . Possible values: name
, createdAt
, iamid
, email
.
string
The order that the results will be sorted in. The default is asc
. Possible values: asc
, desc
.
string
A permission to filter the users by.
Response parameters
Attribute Description integer
Total number of results. May be greater than the length of hits if additional results exist. Use size
and offset
to page additional results.
metadata
Details for each result, including id
, iamid
, userid
, bimAuthorizations
, iamAuthorizations
, authorizations
, projectId
, permissions
, groupPermissions
, profile
, authentication
, systemGenerated
, lastLogin
, lastExternalRefresh
, disabled
, hasLogin
, groups
, createdAt
, updatedAt
, and schema
values. The following details are excluded from the response if the requesting user does not have the USER_ADMIN
Immuta permission: bimAuthorizations
, iamAuthorizations
, and authorizations
.
string
The ID of the IAM the user is connected to.
string
The user's username.
array
The attributes and groups given to the user's BIM profile. This attribute is excluded from the response if the requesting user does not have the USER_ADMIN
Immuta permission.
array
The attributes and groups given to the user's external IAM profile. This attribute is excluded from the response if the requesting user does not have the USER_ADMIN
Immuta permission.
metadata
Details on the user's attributes. This attribute is excluded from the response if the requesting user does not have the USER_ADMIN
Immuta permission.
integer
The project ID for the user's current project.
string
A list of the user's permissions.
metadata
Details on the user, including name
, email
, phone
, about
, location
, organization
, position
, preferences
, externalUserIds
, scim
, systemGenerated
, id
, createdAt
, and updatedAt
values.
timestamp
The date of the user's last Immuta login.
boolean
If true
, the user has been disabled.
boolean
If true
, the user has logged into Immuta.
metadata
Information on the user's groups.
timestamp
The date the user was created.
timestamp
The date of the last time the user's information was updated.
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 ,
"iamid" : "bim" ,
"userid" : "bhoward@immuta.com" ,
"authorizations" : {
"auth" : [
"SOMETHING_ELSE"
]
} ,
"permissions" : [
"CREATE_DATA_SOURCE" ,
"CREATE_PROJECT" ,
"AUDIT"
] ,
"profile" : {
"name" : "Barry Howard" ,
"email" : "bhoward@immuta.com" ,
"preferences" : {
"sortDataSourceState" : {
"column" : "name" ,
"order" : "asc" ,
"size" : 12
} ,
"sortProjectState" : {
"column" : "name" ,
"order" : "asc" ,
"size" : 12
}
} ,
"id" : 5 ,
"createdAt" : "2018-07-05T07:37:06.392Z" ,
"updatedAt" : "2018-07-05T22:32:43.864Z"
} ,
"authentication" : 5 ,
"systemGenerated" : false ,
"lastLogin" : "2018-07-05T22:32:44.167Z" ,
"disabled" : false ,
"createdAt" : "2018-07-05T07:37:05.818Z" ,
"updatedAt" : "2018-07-05T07:37:05.818Z"
}
]
}
View current user's information
GET
/bim/rpc/user/current
Get the currently logged in user's information.
Response parameters
Attribute Description string
The ID of the IAM the user is connected to.
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.
metadata
Details on the user's attributes.
integer
The project ID for the user's current project.
string
A list of the user's permissions.
metadata
Details on the user, including name
, email
, phone
, about
, location
, organization
, position
, preferences
, externalUserIds
, scim
, systemGenerated
, id
, createdAt
, and updatedAt
values.
timestamp
The date of the user's last Immuta login.
boolean
If true
, the user has been disabled.
boolean
If true
, the user has logged into Immuta.
metadata
Information on the user's groups.
timestamp
The date the user was created.
timestamp
The date of the last time the user's information was updated.
Request example
This request will return information on the user that is logged in.
Copy curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/rpc/user/current
Response example
Copy {
"profile" : {
"name" : "Barrett Springer" ,
"email" : "bspringer@immuta.com" ,
"phone" : null ,
"about" : null ,
"location" : null ,
"organization" : null ,
"position" : null ,
"preferences" : null ,
"hdfsUser" : null ,
"id" : 18 ,
"createdAt" : "2018-07-05T07:37:06.569Z" ,
"updatedAt" : "2018-07-05T07:37:06.569Z"
} ,
"permissions" : [
"CREATE_DATA_SOURCE" ,
"CREATE_PROJECT"
] ,
"authorizations" : {
"Roles" : [
"Analyst"
] ,
"Location" : [
"Columbus"
]
} ,
"iamid" : "bim" ,
"userid" : "bspringer@immuta.com" ,
"authorizations" : null ,
"updatedAt" : "2018-07-05T07:37:05.987Z" ,
"systemGenerated" : false ,
"disabled" : false ,
"hasLogin" : true ,
"lastLogin" : "2018-07-05T07:39:56.365Z"
}
View a user's information
GET
/bim/iam/{iamid}/user/{id}
Gets the specified user's aggregated view.
Request parameters
Attribute Description Required
Response parameters
Attribute Description array
Details about the user, including name
, email
, phone
, about
, location
, organization
, position
, preferences
, externalUserIds
, scim
, id
, and the date of creation.
array
Information about the user's tabDataSourceState
, tabProjectState
, sortDataSourceState
, and currentProject
.
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 return information about the user with the ID 2
.
Copy curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/2
Response example
Copy {
"profile" : {
"name" : "John Doe" ,
"email" : "john.doe@immuta.com" ,
"phone" : null ,
"about" : null ,
"location" : null ,
"organization" : null ,
"position" : null ,
"preferences" : {
"sortProjectState" : {
"column" : "name" ,
"order" : "asc" ,
"size" : 12
} ,
"currentProject" : null
} ,
"externalUserIds" : {} ,
"scim" : null ,
"systemGenerated" : false ,
"id" : 2 ,
"createdAt" : "2021-08-16T20:30:43.698Z" ,
"updatedAt" : "2021-09-14T01:17:02.786Z"
} ,
"permissions" : [
"CREATE_DATA_SOURCE_IN_PROJECT" ,
"CREATE_PROJECT" ,
"CREATE_DATA_SOURCE" ,
"USER_ADMIN" ,
"APPLICATION_ADMIN" ,
"AUDIT" ,
"GOVERNANCE" ,
"IMPERSONATE_HDFS_USER" ,
"CREATE_S3_DATASOURCE_WITH_INSTANCE_ROLE" ,
"FETCH_POLICY_INFO" ,
"CREATE_FILTER" ,
"IMPERSONATE_USER" ,
"PROJECT_MANAGEMENT"
] ,
"iamid" : "bim" ,
"userid" : "jane.doe@immuta.com" ,
"authorizations" : {} ,
"updatedAt" : "2021-09-29T17:57:09.059Z" ,
"systemGenerated" : false ,
"disabled" : false ,
"lastLogin" : "2021-09-30T19:20:03.327Z" ,
"lastExternalRefresh" : "2021-09-30T19:20:03.327Z" ,
"bimAuthorizations" : null ,
"iamAuthorizations" : null ,
"hasLogin" : true
}
View a user profile
GET
/bim/iam/{iamid}/user/{userid}/profile
Gets the specified user's profile.
Request parameters
Attribute Description Required
Response parameters
Attribute Description string
The user's phone number.
string
Details about the user.
string
The user's location.
string
The user's organization.
string
The user's position.
array
A list of user IDs for technologies outside of Immuta, if specified as different from the Immuta user ID.
timestamp
The date the user was created.
timestamp
The date the profile was last updated.
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
.
Copy curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/2/profile
Response example
Copy {
"name" : "John Doe" ,
"email" : "john.doe@immuta.com" ,
"phone" : null ,
"about" : null ,
"location" : null ,
"organization" : null ,
"position" : null ,
"preferences" : {
"sortProjectState" : {
"column" : "name" ,
"order" : "asc" ,
"size" : 12
} ,
"currentProject" : null
} ,
"externalUserIds" : {} ,
"scim" : null ,
"systemGenerated" : false ,
"id" : 2 ,
"createdAt" : "2021-08-16T20:30:43.698Z" ,
"updatedAt" : "2021-09-14T01:17:02.786Z"
}
View a user's groups
GET
/bim/iam/{iamid}/user/{userid}/groups
Get the specified user's list of groups.
Request parameters
Attribute Description Required string
The user's username.
Response parameters
Attribute Description integer
The user's ID within the group.
Request example
This example request will return information on the groups of the user with the username john.doe@immuta.com
.
Copy curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/john.doe%40immuta.com/groups
Response example
Copy [
{
"id" : 2 ,
"name" : "API Group #2" ,
"iamid" : "bim" ,
"groupUser" : 6
}
]
Delete a user
DELETE
/bim/iam/bim/user/{userid}
Delete the specified user in Immuta.
Request parameters
Attribute Description Required string
The user's username.
Response parameters
Attribute Description string
The user's username.
Request example
This example request will delete the user with the username charlie.doe@immuta.com
.
Copy curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/charlie.doe%40immuta.com
Response example
Copy {
"userid" : "charlie.doe@immuta.com" ,
"iamid" : "bim"
}
Create a new group
POST
/bim/group
Create a new group.
Payload parameters
Attribute Description Required string
The new group name.
string
The new group's email.
string
The new group's description.
Response parameters
Attribute Description array
The group's attributes.
timestamp
The date the group was created.
timestamp
The date the group was last updated.
Request example
This request with the payload below will create a group through the bim
IAM with the name API Group
.
Copy curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/group
Payload example
Copy {
"iamid" : "bim" ,
"name" : "API Group"
}
Response example
Copy {
"id" : 3 ,
"iamid" : "bim" ,
"name" : "API Group" ,
"gid" : null ,
"email" : null ,
"authorizations" : null ,
"description" : null ,
"scim" : null ,
"scimid" : null ,
"createdAt" : "2021-09-29T15:15:26.615Z" ,
"updatedAt" : "2021-09-29T15:15:26.615Z"
}
Manage groups
Method Path Purpose /bim/group/{groupId}/user/{groupuserid}
/bim/group/{groupId}/user
/bim/iam/{iamid}/group/{groupid}/authorizations
Update a group
PUT
/bim/group/{groupId}
Update the specified group.
Request parameters
Attribute Description Required
Payload parameters
Attribute Description Required string
The group's new name.
string
The group's new email.
string
The group's new description.
Response parameters
Attribute Description string
The group attributes.
string
The group description.
timestamp
The date the group was created.
timestamp
The date the group was last updated.
Request example
This request with the payload below will update the group with the ID 2
with the name API Group #2
and with a new description.
Copy curl \
--request PUT \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/group/2
Payload example
Copy {
"name" : "API Group #2" ,
"description" : "This group was edited through the API"
}
Response example
Copy {
"id" : 2 ,
"iamid" : "bim" ,
"name" : "API Group #2" ,
"gid" : null ,
"email" : "blue.team@immuta.com" ,
"authorizations" : {
"Finance" : [
"CFA"
]
} ,
"description" : "This group was edited through the API" ,
"scim" : null ,
"scimid" : null ,
"createdAt" : "2021-09-16T17:24:55.066Z" ,
"updatedAt" : "2021-09-29T17:32:07.725Z"
}
Remove a user from a group
DELETE
/bim/group/{groupId}/user/{groupuserid}
Remove a user from a group.
Request parameters
Attribute Description Required integer
The user's group ID.
Request example
Copy curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group/1/user/2
Add a user to a group
POST
/bim/group/{groupId}/user
Add a new user to a group.
Request parameters
Attribute Description Required
Payload parameters
Attribute Description Required string
The new user's ID.
string
The new user's IAM.
Response parameters
Attribute Description integer
The user's group ID.
timestamp
The date the user was added to the group.
timestamp
The date the user was last updated within the group.
Request example
This request with the payload below adds the user with the ID tom.jones@immuta.com
to the group with the ID 2
.
Copy curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/group/2/user
Payload example
Copy {
"userid" : "tom.jones@immuta.com" ,
"iamid" : "bim"
}
Response example
Copy {
"id" : 6 ,
"group" : 2 ,
"profile" : 2 ,
"createdAt" : "2021-09-29T17:57:09.054Z" ,
"updatedAt" : "2021-09-29T17:57:09.054Z"
}
Update a group's attributes
PUT
/bim/iam/{iamid}/group/{groupid}/authorizations/{attributeName}/{attributeValue}
Update the specified group's attributes.
Request parameters
Attribute Description Required string
The attribute name.
string
The attribute value.
Response parameters
Attribute Description string
The group attributes.
string
The group description.
timestamp
The date the group was created.
timestamp
The date the group was last updated.
Request example
This example request will add the attribute Finance.Red Team
to the group with the ID 2
.
Copy curl \
--request PUT \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/group/2/authorizations/Finance/Red%20Team
Response example
Copy {
"id" : 2 ,
"iamid" : "bim" ,
"name" : "API Group #2" ,
"gid" : null ,
"email" : "blue.team@immuta.com" ,
"authorizations" : {
"Finance" : [ "CFA" , "Red Team" ]
} ,
"description" : "This group was edited through the API" ,
"scim" : null ,
"scimid" : null ,
"createdAt" : "2021-09-16T17:24:55.066Z" ,
"updatedAt" : "2021-10-08T13:41:06.211Z"
}
Search groups
Method Path Purpose /bim/group/{groupId}/user
Search all groups from all IAMs
GET
/bim/group
Get the list of groups from all configured IAMs.
Query parameters
Attribute Description Required string
A partial name to match against group names.
string[]
Filters results to return groups with specified IDs.
integer
The user ID. This will return the groups that the user is a member of.
string
Optionally provide the IAM to filter the groups.
integer
The maximum number of records to return. The default is 25
.
integer
Offset to start returning values.
string
The field to sort results on. Possible values: name
, createdAt
, iamid
. Default is name
.
string
The order that the results will be sorted in. Possible values: asc
, desc
. The default is asc
.
boolean
If true
, results will only return distinct group names.
Response parameters
Attribute Description integer
Total number of results. May be greater than the length of hits if additional results exist. Use size
and offset
to page additional results.
metadata
Details on each result, including id
, iamid
, name
, gid
, email
, authorizations
, description
, scim
, scimid
, createdAt
, and updatedAt
values. authorizations
is excluded from the response if the requesting user does not have the USER_ADMIN
Immuta permission.
string
The name of the group.
metadata
Details on the group's attributes. This is excluded from the response if the requesting user does not have the USER_ADMIN
Immuta permission.
string
Details attached to the group.
timestamp
The date the group was created.
timestamp
The date the group was last updated.
Request example
This request will return all of the groups in Immuta.
Copy curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group?size= 25 & sortOrder = asc
Response example
Copy {
"count" : "3" ,
"hits" : [
{
"id" : 2 ,
"iamid" : "bim" ,
"name" : "engineers" ,
"gid" : null ,
"email" : "engineers@immuta.com" ,
"authorizations" : null ,
"description" : null ,
"createdAt" : "2018-07-05T07:37:07.209Z" ,
"updatedAt" : "2018-07-05T07:37:07.209Z"
} ,
{
"id" : 1 ,
"iamid" : "bim" ,
"name" : "founders" ,
"gid" : null ,
"email" : null ,
"authorizations" : null ,
"description" : null ,
"createdAt" : "2018-07-05T07:37:07.177Z" ,
"updatedAt" : "2018-07-05T07:37:07.177Z"
} ,
{
"id" : 20 ,
"iamid" : "bim" ,
"name" : "system administrators" ,
"gid" : null ,
"email" : null ,
"authorizations" : null ,
"description" : null ,
"createdAt" : "2018-07-05T07:37:07.595Z" ,
"updatedAt" : "2018-07-05T07:37:07.595Z"
}
]
}
Search a specific group
GET
/bim/group/{groupid}
Get the specified group.
Query parameters
Attribute Description Required integer
The ID of the group.
Response parameters
Attribute Description string
The group's email.
metadata
Details on the group's attributes.
string
The group's description.
timestamp
The date the group was created.
timestamp
The date the group was last updated.
Request example
This request will search for the group with the ID 2
.
Copy curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group/2
Response example
Copy {
"id" : 2 ,
"iamid" : "bim" ,
"name" : "engineers" ,
"gid" : null ,
"email" : "engineers@immuta.com" ,
"authorizations" : {
"Location" : [
"College Park"
]
} ,
"description" : null ,
"createdAt" : "2018-07-05T07:37:07.209Z" ,
"updatedAt" : "2018-07-06T01:42:55.518Z"
}
Search a group's users
GET
/bim/group/{groupid}/user
Get group users.
Query parameters
Attribute Description Required integer
The ID of the group.
integer
Offset to start returning values.
integer
The maximum number of records to return. The default is 25
.
string
The order that the results will be sorted in. Possible values: asc
, desc
. The default is asc
.
Response parameters
Attribute Description integer
Total number of results. May be greater than the length of hits if additional results exist. Use size
and offset
to page additional results.
metadata
Details for each result, including id
, group
, profile
, uid
, iamid
, userid
, disabled
, scim
, scimid
, createdAt
, and updatedAt
values.
string
The ID of the IAM the user is connected to.
string
The user's username.
metadata
Details on the user, including iamid
, userid
, name
, email
, phone
, about
, location
, organization
, position
, preferences
, externalUserIds
, scim
, systemGenerated
, id
, createdAt
, and updatedAt
values.
boolean
If true
, the user has been disabled.
timestamp
The date the user was created.
timestamp
The date of the last time the user's information was updated.
Request example
This request will return information on the users in the group with the ID 2
.
Copy curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group/2/user
Response example
Copy {
"count" : 2 ,
"hits" : [
{
"id" : 1 ,
"group" : 2 ,
"profile" : {
"name" : "Willie Gomez" ,
"email" : "wgomez@immuta.com" ,
"phone" : null ,
"about" : null ,
"location" : null ,
"organization" : null ,
"position" : null ,
"preferences" : {
"tabDataSourceState" : 1 ,
"tabProjectState" : 1
} ,
"hdfsUser" : "wgomez" ,
"id" : 3 ,
"createdAt" : "2018-07-05T07:37:06.373Z" ,
"updatedAt" : "2018-07-05T07:37:06.373Z"
} ,
"createdAt" : "2015-08-23T00:00:00.000Z" ,
"updatedAt" : "2018-07-05T07:37:07.283Z" ,
"userid" : "wgomez@immuta.com" ,
"iamid" : "bim"
} ,
{
"id" : 2 ,
"group" : 2 ,
"profile" : {
"name" : "Helen James" ,
"email" : "hjames@immuta.com" ,
"phone" : null ,
"about" : null ,
"location" : null ,
"organization" : null ,
"position" : null ,
"preferences" : null ,
"hdfsUser" : null ,
"id" : 13 ,
"createdAt" : "2018-07-05T07:37:06.470Z" ,
"updatedAt" : "2018-07-05T07:37:06.470Z"
} ,
"createdAt" : "2018-07-05T07:37:07.291Z" ,
"updatedAt" : "2018-07-05T07:37:07.291Z" ,
"userid" : "hjames@immuta.com" ,
"iamid" : "bim"
}
]
}
Delete a group
DELETE
/bim/group/{groupId}
Delete the specified group.
Query parameters
Attribute Description Required
Request example
This request will delete the group with the ID 3
.
Copy curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group/3
Authenticate a user and create a project API key
POST
/bim/apikey
Authenticate the user and create a project API key.
Payload parameters
Attribute Description Required string
The name to associate with the API key.
The payload must have one or both of the two attributes above.
Response parameters
Attribute Description integer
The new API key's ID.
string
The name of the API key.
Request example
This example request with the payload below will authenticate the user Jane Doe
in the project with the ID 1
and create a new API key for her.
Copy curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/apikey
Payload example
Copy {
"projectId" : 1 ,
"name" : "My Project API Key"
}
Response example
Copy {
"apikey" : "******" ,
"keyid" : 334 ,
"project" : 1 ,
"name" : "My Project API Key" ,
"context" : null
}
Authenticate with an API key
Authenticate a user with an API key
POST
/bim/apikey/authenticate
Authenticate with the Immuta API using an API key.
Payload parameters
Response parameters
Attribute Description boolean
If true
, the user has been successfully authenticated.
string
The user's access token.
Request example
This example request will authenticate the user with the Immuta API.
Copy curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/apikey/authenticate
Payload example
Copy {
"apikey" : "100874dyour-api-key-79aa38bbfe0e8c787"
}
Response example
Copy {
"authenticated" : true ,
"token" : "be420************2745ea0307"
}
Impersonate a user with an API key
POST
/bim/apikey/impersonate
Impersonate another user using an API key.
Payload parameters
Attribute Description string
The API key of the account with the user impersonation permission.
string
The username of the impersonated user.
string
The IAM ID of the impersonated user.
integer
The project ID of the impersonated user.
Response parameters
Attribute Description boolean
If true
, the user has been successfully authenticated.
string
The user's access token.
Request example
This example request will allow the requesting user to impersonate the user specified in example-payload.json
.
Copy curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/apikey/impersonate
Payload example
Copy {
"apikey" : "requesting-users-api-key" ,
"userid" : "user1@example.com" ,
"iamid" : "bim"
}
Response example
Copy {
"authenticated" : true ,
"token" : "0753*************c61d2"
}
View tokens and API keys
Method Path Purpose /bim/iam/{iamid}/user/{userid}/apikeys
View token information
POST
/bim/token
Get information for a given token, should it exist.
Payload parameters
Response parameters
Attribute Description integer
The access token ID.
string
The token type: bearer
.
string
The user's username.
integer
If the token was generated using a project API key, this is the project ID.
timestamp
The date the token was created.
timestamp
The date the token was last used.
timestamp
The date the token will expire.
timestamp
The date the token was created.
timestamp
The date the token was last updated.
string
The scope of the token, such as impersonation
.
string
The user ID of the impersonating user.
string
The IAM ID of the impersonating user.
Request example
This example request will return information on the access token in the payload.
Copy curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/token
Payload example
Copy {
"token" : "48983da*********85220837d"
}
Response example
Copy {
"id" : 384 ,
"type" : "bearer" ,
"iamid" : "bim" ,
"userid" : "jane.doe@immuta.com" ,
"project" : null ,
"context" : null ,
"token" : "4898*********220837d" ,
"created" : "2021-10-15T03:59:03.000Z" ,
"lastUsed" : "2021-10-15T03:59:57.185Z" ,
"expiration" : "2021-10-15T04:59:57.185Z" ,
"name" : null ,
"application" : null ,
"derivedFrom" : null ,
"createdAt" : "2021-10-15T03:59:03.562Z" ,
"updatedAt" : "2021-10-15T03:59:57.186Z" ,
"scopes" : null ,
"impersonationuserid" : null ,
"impersonationiamid" : null
}
View a user's API keys
GET
/bim/iam/{iamid}/user/{userid}/apikeys
Get metadata for all of the user's API keys.
Request parameters
Attribute Description Required string
The user's username.
Response parameters
Attribute Description timestamp
The date the API key was created.
array
Information on the project attached to the API key, including values for name
, status
, description
, documentation
, deleted
, allowMaskedJoins
, subscriptionType
, subscriptionPolicy
, equalization
, snowflake
, salt
, type
, schema
, id
, createdAt
, updatedAt
, workspace
, createdBy
, updatedBy
, and schemaEvolutionId
.
timestamp
The date the API key was last used.
Request example
This example request will return information on the API keys of the user with the username john.doe@immuta.com
.
Copy curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/john.doe%40immuta.com/apikeys
Response example
Copy [
{
"keyid" : 323 ,
"created" : "2021-10-06T18:28:13.000Z" ,
"project" : {
"projectKey" : "Credit Payments" ,
"name" : "Credit Payments" ,
"status" : "open" ,
"description": "This project contains all data sources under the schema, credit_payments, from admin@snowflake.demo-databases.prod.immuta.com:3306/credit_payments.",
"documentation": "This is an automatically generated project that collects data sources under the schema, credit_payments, from admin@snowflake.demo-databases.prod.immuta.com:3306/credit_payments. When data sources in this schema are added to the system, they will automatically be added to this project.",
"deleted" : false ,
"allowMaskedJoins" : false ,
"subscriptionType" : "manual" ,
"subscriptionPolicy" : null ,
"equalization" : null ,
"snowflake" : null ,
"salt" : "e0c4a8c5-2a5b-4488-9c43-cb3d816172f4" ,
"type" : "Schema" ,
"schema" : "credit_payments" ,
"id" : 3 ,
"createdAt" : "2021-09-09T17:06:39.839Z" ,
"updatedAt" : "2021-09-09T17:06:39.839Z" ,
"workspace" : null ,
"createdBy" : 2 ,
"updatedBy" : 2 ,
"schemaEvolutionId" : 2
} ,
"lastUsed" : "2021-10-06T18:28:13.341Z" ,
"name" : "Credit Payments" ,
"context" : null
}
]
Delete an API key
DELETE
/bim/apikey/{keyid}
Delete an API key, all auth tokens issued using that API key, and generate a new API key.
Request parameters
Attribute Description Required
Response parameters
Attribute Description integer
The number of tokens revoked.
Request example
This example request will delete the API key with the ID 323
, revoke all the auth tokens issued using that API key, and generate a new API key.
Copy curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/apikey/323
Response example
Copy {
"revokedTokens" : 1
}