BIM API Reference Guide
This page details the bim
API, which allows users to programmatically access information
about users, their group memberships, and authentications. Most of
the actions described here require ADMIN permissions.
Note
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 an API Key.
- Authenticate with an API key.
- View tokens and API key information.
- Remove an API key.
Create a new user
Endpoint
Method | Path | Purpose |
---|---|---|
POST | /bim/iam/bim/user |
Create a new BIM user. |
Request Parameters
None.
Payload Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
userid | string The new user's username. |
Yes |
password | string The new user's password. |
No |
profile | array Information on the new user's name and email. |
No |
permissions | array Information on the new user's permissions. |
No |
Response Parameters
Attribute | Description |
---|---|
id | integer The user ID. |
iamid | string The IAM ID. |
userid | string The user's username. |
bimAuthorizations | array The attributes and groups given to the user's BIM profile. |
iamAuthorizations | array The attributes and groups given to the user's external IAM profile. |
authorizations | array The user's groups and attributes. |
permissions | array The user's permissions. |
profile | array Details on the user, including name , email , phone , about , location , organization , position , preferences , externalUserIds , scim , systemGenerated , id , createdAt , and updatedAt values. |
lastLogin | timestamp The date the user most recently logged into Immuta. |
disabled | boolean If true , the user is disabled. |
createdAt | timestamp The date the user was created. |
updatedAt | timestamp The date the user was last updated. |
newUserLink | string A link for the new user to log in and create a password. |
emailFailed | boolean If true , the login email was unable to be sent to the user's provided email address. |
emailSent | boolean If true , a login email was sent to the new user. |
Request example
This example request with the payload below will create a new BIM user with the username charlie.doe@immuta.com
.
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
{
"iamid": "bim",
"userid": "charlie.doe@immuta.com",
"profile": {
"name": "Charlie Doe",
"email": "charlie.doe@immuta.com"
},
"permissions": []
}
Response example
{
"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 |
---|---|---|
GET | /bim/iam/{iamid}/user/authenticate |
Authenticate a user from a 3rd party identity provider. |
POST | /bim/iam/{iamid}/user/authenticate |
Authenticate a user using their username and password and proxying it to the specified IAM service. |
PUT | /bim/iam/{iamid}/user/{userid}/profile |
Update a specified user's profile. |
DELETE | /bim/iam/{iamid}/user/{userid}/permissions/{permission} |
Remove the specified user's permission. |
PUT | /bim/iam/{iamid}/user/{userid}/permissions |
Update the specified user's permissions. |
PUT | /bim/iam/{iamid}/user/{userid}/password |
Update the specified user's password. |
PUT | /bim/iam/{iamid}/user/{userid}/disable/{disable} |
Disable / enable the specified BIM user. |
POST | /bim/syncUsers |
Sync Users for external IAM. |
POST | /iam/{iamId}/sync |
Sync LDAP users with Immuta. |
PUT | /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue} |
Update the specified user's attributes. |
DELETE | /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value} |
Remove an attribute from the specified group or user. |
POST | /bim/iam/bim/user/{userid}/clone |
Clones the provided user to create multiple additional user accounts. |
Authenticate a user from an outside IAM
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/iam/{iamid}/user/authenticate |
Authenticate a user from a 3rd-party identity provider. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
Response Parameters
None.
Request example
This example request
curl \
--request POST \
--header "Content-Type: application/json" \
https://demo.immuta.com/LDAPIAM/user/authenticate
Authenticate user with username and password
Endpoint
Method | Path | Purpose |
---|---|---|
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 |
---|---|---|
iamid | string The IAM ID. |
Yes |
Payload Parameters
Attribute | Description | Required |
---|---|---|
username | string The user's username for the IAM dictated in the request. |
Yes |
password | string The user's password for the IAM dictated in the request. |
Yes |
Response Parameters
Attribute | Description |
---|---|
authenticated | boolean If true , the user has been successfully authenticated. |
token | string The user's access token. |
tokenExpiration | timestamp The date the token will expire. |
profileId | integer The user ID. |
Request example
This example request with the payload below will authenticate the user using the bim
IAM.
curl \
--request POST \
--header "Content-Type: application/json" \
--data @example-payload.json \
https://demo.immuta.com/bim/iam/bim/user/authenticate
Payload example
{
"username": "demo.user@immuta.com",
"password": "********"
}
Response example
{
"authenticated": true,
"token": "6913229***********0d3da",
"tokenExpiration": "2021-09-29T19:12:51.467Z"
}
Update a user profile
Endpoint
Method | Path | Purpose |
---|---|---|
PUT | /bim/iam/{iamid}/user/{userid}/profile |
Update a specified user's profile. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
userId | string The user's username. |
Yes |
Payload Parameters
Attribute | Description | Required |
---|---|---|
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 , redshiftUser , and teradataUser . |
No |
preferences | array |
No |
scim | array |
No |
Response Parameters
Attribute | Description |
---|---|
profile | array Details information about the user, including name , email , phone , about , location , organization , position , preferences , externalUserIds , scim , id , and the date of creation. |
permissions | array A list of the user's permissions. |
iamid | string The IAM ID. |
userid | string The user's username. |
authorizations | array The user's attributes and groups. |
updatedAt | timestamp The date the user was last updated. |
disabled | boolean If true , the user is disabled. |
lastLogin | timestamp The date the user last logged in. |
bimAuthorizations | array The attributes and groups given to the user's BIM profile. |
iamAuthorizations | array The attributes and groups given to the user's external IAM profile. |
hasLogin | boolean If true , the user has logged into Immuta. |
Request example
This example request will change the location to Boston, MA
for the user with the username jane.doe@immuta.com
.
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
{
"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
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
DELETE | /bim/iam/{iamid}/user/{userid}/permissions/{permission} |
Remove the specified user's permission. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
userid | string The user's username. |
Yes |
permission | string The permission to remove. See Immuta permissions and personas for a list of Immuta permissions. |
Yes |
Response Parameters
Attribute | Description |
---|---|
id | integer The user's ID. |
iamid | string The IAM ID. |
userid | string The user's username. |
bimAuthorizations | array The attributes and groups given to the user's BIM profile. |
iamAuthorizations | array The attributes and groups given to the user's external IAM profile. |
authorizations | array Details on the user's groups and attributes. |
permissions | array[string] A list of the user's permissions. |
profile | integer The user's profile ID. |
lastLogin | timestamp The date the user last logged into Immuta. |
disabled | boolean If true , the user is disabled. |
createdAt | timestamp The date the user was created. |
updatedAt | timestamp The date the user was last updated. |
Request example
This example request will delete the permission CREATE_DATA_SOURCE_IN_PROJECT
from the user with the username john.doe@immuta.com
.
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
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
PUT | /bim/iam/{iamid}/user/{userid}/permissions |
Update the specified user's permission. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
userid | string The user's username. |
Yes |
Request Parameters
Attribute | Description | Required |
---|---|---|
permissions | array[string] A list of the user's permissions. This list is going to be a comprehensive list of all of the user's permissions. See Immuta permissions and personas for a list of Immuta permissions. |
Yes |
Response Parameters
Attribute | Description |
---|---|
id | integer The user's ID. |
iamid | string The IAM ID. |
userid | string The user's username. |
bimAuthorizations | array The attributes and groups given to the user's BIM profile. |
iamAuthorizations | array The attributes and groups given to the user's external IAM profile. |
authorizations | array Details on the user's groups and attributes. |
permissions | array A list of the user's permissions. |
profile | integer The user's profile ID. |
lastLogin | timestamp The date the user last logged into Immuta. |
disabled | boolean If true , the user is disabled. |
createdAt | timestamp The date the user was created. |
updatedAt | timestamp The date the user was last updated. |
Request example
This example request with the payload below will change to permissions of the user with the
username charlie.doe@immuta.com
to CREATE_DATA_SOURCE_IN_PROJECT
, CREATE_PROJECT
, and CREATE_DATA_SOURCE
.
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
[
"CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT", "CREATE_DATA_SOURCE"
]
Response example
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
PUT | /bim/iam/{iamid}/user/{userid}/password |
Update the specified user's password. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
userid | string The user's username. |
Yes |
Request Parameters
Attribute | Description | Required |
---|---|---|
originalPassword | string The user's old password. |
Yes |
password | string The user's new password. |
Yes |
Response Parameters
Attribute | Description |
---|---|
success | boolean If true , the user's password has been successfully changed to the new password. |
Request example
This example request with the payload below will change the password of the user with the ID jane.doe@immuta.com
.
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
{
"originalPassword": "old********",
"password": "new********"
}
Response example
{
"success": true
}
Disable or enable a user
Endpoint
Method | Path | Purpose |
---|---|---|
PUT | /bim/iam/{iamid}/user/{userid}/disable/{disable} |
Disable / enable the specified BIM user. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
userid | string The user's username. |
Yes |
disable | boolean If true , the user will be disabled. |
Yes |
Response Parameters
Attribute | Description |
---|---|
userid | string The user's username. |
disabled | boolean If true , the user is disabled. |
Request example
This example request will disabled the user with the username jane.doe@immuta.com
.
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
{
"userid": "jane.doe@immuta.com",
"disabled": true
}
Sync users from an external IAM
Endpoint
Method | Path | Purpose |
---|---|---|
POST | /bim/syncUsers |
Sync users from an external IAM. |
Request Parameters
None.
Payload Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The external IAM ID. |
Yes |
Response Parameters
None.
Request example
This example request will sync the users from the specified external IAM with Immuta.
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/syncUsers
Payload example
{
"iamid": "ldap"
}
Sync LDAP users with Immuta
Endpoint
Method | Path | Purpose |
---|---|---|
POST | /iam/{iamId}/sync |
Sync LDAP users with Immuta. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamId | string The external IAM ID. |
Yes |
Payload Parameters
Attribute | Description | Required |
---|---|---|
dryRun | boolean If true , no updates will actually be made. |
Yes |
iamConfig | array Details about the IAM configuration, including authenticationOnly , credentials , defaultPermissions , displayName , id , ldapSync , and options . |
No |
plugin | string The type of plugin the IAM uses, ldap . |
No |
schema | array Details about the IAM schema, including group , profile , authorizations , and externalUserIds . |
No |
supportedActions | string |
No |
type |
string The type of IAM, ldap . |
No |
Response Parameters
Attribute | Description |
---|---|
totalCount | integer The total number of users in the external IAM that could be synced over into Immuta. |
importedUsers | array Details about the users who were successfully imported from the sync, including userId and dn . |
refreshedUsers | array Details about the users who were successfully refreshed from the sync, including userId and dn . |
disabledUsers | array Details about the users who were successfully disabled from the sync, including userId and dn . |
enabledUsers | array Details about the users who were successfully enabled from the sync, including userId and dn . |
runningInBackground | boolean If true , the sync created a job to run in the background. |
count | integer The number of users successfully updated from the IAM. |
Request example
This example request will sync the users from Jump Cloud with Immuta.
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
{
"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
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
PUT | /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue} |
Update the specified user's attributes. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
modelType | string The type of model the attribute is added to. Options include group or user . |
Yes |
modelID | string The user or group ID. |
Yes |
attributeName | string The attribute name. |
Yes |
attributeValue | string The attribute value. |
Yes |
Response Parameters
Attribute | Description |
---|---|
id | integer The user or group ID. |
iamid | string The IAM ID. |
userid | string The user's username. |
name | string The group name. |
bimAuthorizations | array The attributes and groups given to the user's BIM profile. |
iamAuthorizations | array The attributes and groups given to the user's external IAM profile. |
authorizations | array Details on the user's or group's and attributes. |
permissions | array A list of the user's permissions. |
profile | integer The user's profile ID. |
lastLogin | timestamp The date the user last logged into Immuta. |
disabled | boolean If true , the user is disabled. |
createdAt | timestamp The date the user was created. |
updatedAt | timestamp The date the user was last updated. |
Request example
This example request will add the attribute Finance.Red Team
to the user with the username jane.doe@immuta.com
.
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
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
DELETE | /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value} |
Remove an attribute from the specified group or user. |
Request Parameters
Attribute | Description | Required |
---|---|---|
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 |
Response Parameters
Attribute | Description |
---|---|
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. |
Request example
This example request will remove the attribute Country.JP
from the user with the user ID jane.doe@immuta.com
.
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
{
"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.
Endpoint
Method | Path | Purpose |
---|---|---|
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 |
---|---|---|
userId | string The user's username. |
Yes |
Payload Parameters
Attribute | Description | Required |
---|---|---|
array The list of new users' emails. |
Yes |
Response Parameters
Attribute | Description |
---|---|
failedEmails | 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
.
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
[
"john.doe@demo.com"
]
Response example
{
"failedEmails": []
}
Review user information
Method | Path | Purpose |
---|---|---|
GET | /bim/iam |
Get a listing of configured IAM services. |
GET | /bim/user |
Administrative search over the aggregated view of all users. |
GET | /bim/rpc/user/current |
Get the currently logged in user's information. |
GET | /bim/iam/{iamid}/user/{id} |
Get the specified user's aggregated view. |
GET | /bim/iam/{iamid}/user/{userid}/profile |
Get the specified user's profile. |
GET | /bim/iam/{iamid}/user/{userid}/groups |
Get the specified user's list of groups. |
Search all IAMs
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/iam |
Get a listing of configured IAM services. |
Query Parameters
None.
Response Parameters
Attribute | Description |
---|---|
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. |
Request example
The request below will list all of the IAMs in use.
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam
Response example
[
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/user |
Administrative search over the aggregated view of all users. |
Query Parameters
Attribute | Description | Required |
---|---|---|
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. |
No |
string A partial email address to match against user email addresses. |
No | |
iamid | string[] Optionally provide the IAM to filter the users. |
No |
profileIds | string[] Filters results to return users with the specified profile IDs. |
No |
excludeSystemGenerated | boolean If true , the results will exclude accounts automatically created for handlers that periodically crawl and ingest. |
No |
excludeAdminAndGovernor | boolean If true , Admin and Governor accounts will be excluded. |
No |
excludeDeletediams | boolean If true , the results will exclude users for any IAMs that are no longer configured. |
No |
excludebim | boolean If true , users from the Immuta internal identity manager will be excluded. |
No |
includeDisabled | boolean If true , the results will include disabled users. |
No |
offset | integer Offset to start returning values. |
No |
sortField | string The field to sort results on. The default is user name. Possible values: name , createdAt , iamid , email . |
No |
sortOrder | string The order that the results will be sorted in. The default is asc . Possible values: asc , desc . |
No |
permission | string A permission to filter the users by. |
No |
Response Parameters
Attribute | Description |
---|---|
count | 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. |
hits | 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. |
id | integer The user ID. |
iamid | string The ID of the IAM the user is connected to. |
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 | metadata Details on the user's attributes. |
projectId | integer The project ID for the user's current project. |
permissions | string A list of the user's permissions. |
profile | metadata 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 of the user's last Immuta login. |
disabled | boolean If true , the user has been disabled. |
hasLogin | boolean If true , the user has logged into Immuta. |
groups | metadata Information on the user's groups. |
createdAt | timestamp The date the user was created. |
updatedAt | 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.
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
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/rpc/user/current |
Get the currently logged in user's information. |
Query Parameters
None.
Response Parameters
Attribute | Description |
---|---|
id | integer The user ID. |
iamid | string The ID of the IAM the user is connected to. |
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 | metadata Details on the user's attributes. |
projectId | integer The project ID for the user's current project. |
permissions | string A list of the user's permissions. |
profile | metadata 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 of the user's last Immuta login. |
disabled | boolean If true , the user has been disabled. |
hasLogin | boolean If true , the user has logged into Immuta. |
groups | metadata Information on the user's groups. |
createdAt | timestamp The date the user was created. |
updatedAt | 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.
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/rpc/user/current
Response example
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/iam/{iamid}/user/{id} |
Gets the specified user's aggregated view. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
id | integer The user ID. |
Yes |
params | query |
No |
Response Parameters
Attribute | Description |
---|---|
profile | array Details about the user, including name , email , phone , about , location , organization , position , preferences , externalUserIds , scim , id , and the date of creation. |
preferences | array Information about the user's tabDataSourceState , tabProjectState , sortDataSourceState , and currentProject . |
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. |
systemGenerated | boolean |
disabled | boolean If true , the user is disabled. |
lastLogin | timestamp The date the user last logged in. |
lastExternalRefresh | timestamp |
bimAuthorizations | array The attributes and groups given to the user's BIM profile. |
iamAuthorizations | array The attributes and groups given to the user's external IAM profile. |
hasLogin | boolean If true , the user has logged into Immuta. |
Request example
This example request will return information about the user with the ID 2
.
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/2
Response example
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/iam/{iamid}/user/{userid}/profile |
Gets the specified user's profile. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
id | integer The user ID. |
Yes |
Response Parameters
Attribute | Description |
---|---|
name | string The user's name. |
string The user's email. |
|
phone | string The user's phone number. |
about | string Details about the user. |
location | string The user's location. |
organization | string The user's organization. |
position | string The user's position. |
externalUserIds | array A list of user IDs for technologies outside of Immuta, if specified as different from the Immuta user ID. |
createdAt | timestamp The date the user was created. |
updatedAt | timestamp The date the profile was last updated. |
preferences | 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
.
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/2/profile
Response example
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/iam/{iamid}/user/{userid}/groups |
Get the specified user's list of groups. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
userid | string The user's username. |
Yes |
Response Parameters
Attribute | Description |
---|---|
id | integer The group ID. |
name | string The group name. |
iamid | string The IAM ID. |
groupUser | 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
.
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
[
{
"id": 2,
"name": "API Group #2",
"iamid": "bim",
"groupUser": 6
}
]
Delete a user
Endpoint
Method | Path | Purpose |
---|---|---|
DELETE | /bim/iam/bim/user/{userid} |
Delete the specified user in Immuta. |
Request Parameters
Attribute | Description | Required |
---|---|---|
userid | string The user's username. |
Yes |
Response Parameters
Attribute | Description |
---|---|
userid | string The user's username. |
iamid | string The IAM ID. |
Request example
This example request will delete the user with the username charlie.doe@immuta.com
.
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
{
"userid": "charlie.doe@immuta.com",
"iamid": "bim"
}
Create a new group
Endpoint
Method | Path | Purpose |
---|---|---|
POST | /bim/group |
Create a new group. |
Query Parameters
None.
Payload Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
name | string The new group name. |
Yes |
string The new group's email. |
No | |
description | string The new group's description. |
No |
Response Parameters
Attribute | Description |
---|---|
id | integer The group ID. |
iamid | string The IAM ID. |
name | string The group name. |
string The group email. |
|
authorizations | array The group's attributes. |
description | The group description. |
createdAt | timestamp The date the group was created. |
updatedAt | 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
.
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/group
Payload example
{
"iamid": "bim",
"name": "API Group"
}
Response example
{
"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 |
---|---|---|
PUT | /bim/group/{groupId} |
Update the specified group. |
DELETE | /bim/group/{groupId}/user/{groupuserid} |
Remove a user from a group. |
POST | /bim/group/{groupId}/user |
Add a new user to a group. |
PUT | /bim/iam/{iamid}/group/{groupid}/authorizations |
Update the specified group's authorizations. |
Update a group
Endpoint
Method | Path | Purpose |
---|---|---|
PUT | /bim/group/{groupId} |
Update the specified group. |
Request Parameters
Attribute | Description | Required |
---|---|---|
groupId | integer The group ID. |
Yes |
Payload Parameters
Attribute | Description | Required |
---|---|---|
name | string The group's new name. |
No |
string The group's new email. |
No | |
description | string The group's new description. |
No |
Response Parameters
Attribute | Description |
---|---|
id | integer The group ID. |
iamid | string The IAM ID. |
name | string The group name. |
string The group email. |
|
authorizations | string The group attributes. |
description | string The group description. |
createdAt | timestamp The date the group was created. |
updatedAt | 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.
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
{
"name": "API Group #2",
"description": "This group was edited through the API"
}
Response example
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
DELETE | bim/group/{groupId}/user/{groupuserid} |
Remove a user from a group. |
Request Parameters
Attribute | Description | Required |
---|---|---|
groupId | integer The group ID. |
Yes |
groupuserid | integer The user's group ID. |
Yes |
Response Parameters
None.
Request example
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
Endpoint
Method | Path | Purpose |
---|---|---|
POST | bim/group/{groupId}/user |
Add a new user to a group. |
Request Parameters
Attribute | Description | Required |
---|---|---|
groupId | integer The group ID. |
Yes |
Payload Parameters
Attribute | Description | Required |
---|---|---|
userid | string The new user's ID. |
Yes |
iamid | string The new user's IAM. |
Yes |
Response Parameters
Attribute | Description |
---|---|
id | integer The user's group ID. |
group | integer The group ID. |
profile | integer The user ID. |
createdAt | timestamp The date the user was added to the group. |
updatedAt | 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
.
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
{
"userid": "tom.jones@immuta.com",
"iamid": "bim"
}
Response example
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
PUT | /bim/iam/{iamid}/group/{groupid}/authorizations/{attributeName}/{attributeValue} |
Update the specified group's attributes. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
groupId | integer The group ID. |
Yes |
attributeName | string The attribute name. |
Yes |
attributeValue | string The attribute value. |
Yes |
Response Parameters
Attribute | Description |
---|---|
id | integer The group ID. |
iamid | string The IAM ID. |
name | string The group name. |
string The group email. |
|
authorizations | string The group attributes. |
description | string The group description. |
createdAt | timestamp The date the group was created. |
updatedAt | 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
.
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
{
"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 |
---|---|---|
GET | /bim/group |
Get the list of groups from all configured IAMs. |
GET | /bim/group/{groupId} |
Get the specified group. |
GET | /bim/group/{groupId}/user |
Get group users. |
Search all groups from all IAMs
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/group |
Get the list of groups from all configured IAMs. |
Query Parameters
Attribute | Description | Required |
---|---|---|
name | string A partial name to match against group names. |
No |
ids | string[] Filters results to return groups with specified IDs. |
No |
userid | integer The user ID. This will return the groups that the user is a member of. |
No |
iamid | string Optionally provide the IAM to filter the groups. |
No |
size | integer The maximum number of records to return. The default is 25 . |
No |
offset | integer Offset to start returning values. |
No |
sortField | string The field to sort results on. Possible values: name , createdAt , iamid . Default is name . |
No |
sortOrder | string The order that the results will be sorted in. Possible values: asc , desc . The default is asc . |
No |
nameOnly | boolean If true , results will only return distinct group names. |
No |
Response Parameters
Attribute | Description |
---|---|
count | 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. |
hits | metadata Details on each result, including id , iamid , name , gid , email , authorizations , description , scim , scimid , createdAt , and updatedAt values. |
id | integer The group ID. |
iamid | string The IAM ID. |
name | string The name of the group. |
string The group email. |
|
authorizations | metadata Details on the group's attributes. |
descriptions | string Details attached to the group. |
createdAt | timestamp The date the group was created. |
updatedAt | timestamp The date the group was last updated. |
Request example
This request will return all of the groups in Immuta.
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group?size=25&sortOrder=asc
Response example
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/group/{groupid} |
Get the specified group. |
Query Parameters
Attribute | Description | Required |
---|---|---|
groupId | integer The ID of the group. |
Yes |
Response Parameters
Attribute | Description |
---|---|
id | integer The group's ID. |
iamid | string The IAM ID. |
name | string The group's name. |
string The group's email. |
|
authorizations | metadata Details on the group's attributes. |
descriptions | string The group's description. |
createdAt | timestamp The date the group was created. |
updatedAt | timestamp The date the group was last updated. |
Request example
This request will search for the group with the ID 2
.
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group/2
Response example
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/group/{groupid}/user |
Get group users. |
Query Parameters
Attribute | Description | Required |
---|---|---|
groupId | integer The ID of the group. |
Yes |
offset | integer Offset to start returning values. |
No |
size | integer The maximum number of records to return. The default is 25 . |
No |
sortOrder | string The order that the results will be sorted in. Possible values: asc , desc . The default is asc . |
No |
Response Parameters
Attribute | Description |
---|---|
count | 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. |
hits | metadata Details for each result, including id , group , profile , uid , iamid , userid , disabled , scim , scimid , createdAt , and updatedAt values. |
id | integer The group ID. |
iamid | string The ID of the IAM the user is connected to. |
userid | string The user's username. |
profile | metadata Details on the user, including iamid , userid , name , email , phone , about , location , organization , position , preferences , externalUserIds , scim , systemGenerated , id , createdAt , and updatedAt values. |
disabled | boolean If true , the user has been disabled. |
group | integer The group ID. |
createdAt | timestamp The date the user was created. |
updatedAt | 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
.
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group/2/user
Response example
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
DELETE | /bim/group/{groupId} |
Delete the specified group. |
Query Parameters
Attribute | Description | Required |
---|---|---|
groupId | integer The group ID. |
Yes |
Response Parameters
None.
Request example
This request will delete the group with the ID 3
.
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
Endpoint
Method | Path | Purpose |
---|---|---|
POST | /bim/apikey |
Authenticate the user and create a project API key. |
Request Parameters
None.
Payload Parameters
Attribute | Description | Required |
---|---|---|
projectId | integer The project ID. |
No |
name | string The name to associate with the API key. |
No |
The payload must have one or both of the two attributes above.
Response Parameters
Attribute | Description |
---|---|
apikey | string The new API key. |
keyid | integer The new API key's ID. |
project | integer The project ID. |
name | 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.
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/apikey
Payload example
{
"projectId": 1,
"name": "My Project API Key"
}
Response example
{
"apikey": "******",
"keyid": 334,
"project": 1,
"name": "My Project API Key",
"context": null
}
Authenticate with an API key
Method | Path | Purpose |
---|---|---|
POST | /bim/apikey/authenticate |
Authenticate with the Immuta API using an API key. |
POST | /bim/apikey/impersonate |
Impersonate another user using an API key. |
Authenticate a user with an API key
Endpoint
Method | Path | Purpose |
---|---|---|
POST | /bim/apikey/authenticate |
Authenticate with the Immuta API using an API key. |
Request Parameters
None.
Payload Parameters
Attribute | Description |
---|---|
apikey | string The API key. |
Response Parameters
Attribute | Description |
---|---|
authenticated | boolean If true , the user has been successfully authenticated. |
token | string The user's access token. |
Request example
This example request will authenticate the user with the Immuta API.
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
{
"apikey": "100874dyour-api-key-79aa38bbfe0e8c787"
}
Response example
{
"authenticated": true,
"token": "be420************2745ea0307"
}
Impersonate a user with an API key
Endpoint
Method | Path | Purpose |
---|---|---|
POST | /bim/apikey/impersonate |
Impersonate another user using an API key. |
Request Parameters
None.
Payload Parameters
Attribute | Description |
---|---|
apikey | string The API key of the account with the user impersonation permission. |
userid | string The username of the impersonated user. |
iamid | string The IAM ID of the impersonated user. |
projectId | integer The project ID of the impersonated user. |
Response Parameters
Attribute | Description |
---|---|
authenticated | boolean If true , the user has been successfully authenticated. |
token | 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
.
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
{
"apikey": "requesting-users-api-key",
"userid": "user1@example.com",
"iamid": "bim"
}
Response example
{
"authenticated": true,
"token": "0753*************c61d2"
}
View tokens and API keys
Method | Path | Purpose |
---|---|---|
POST | /bim/token |
Get information for a given token, should it exist. |
GET | /bim/iam/{iamid}/user/{userid}/apikeys |
Get metadata for all of the user's API Keys. |
View token information
Endpoint
Method | Path | Purpose |
---|---|---|
POST | /bim/token |
Get information for a given token, should it exist. |
Request Parameters
None.
Payload Parameters
Attribute | Description |
---|---|
token | string The access token. |
Response Parameters
Attribute | Description |
---|---|
id | integer The access token ID. |
type | string The token type: bearer . |
iamid | string The IAM ID. |
userid | string The user's username. |
project | integer If the token was generated using a project API key, this is the project ID. |
token | string The access token. |
created | timestamp The date the token was created. |
lastUsed | timestamp The date the token was last used. |
expiration | timestamp The date the token will expire. |
name | string The token name. |
createdAt | timestamp The date the token was created. |
updatedAt | timestamp The date the token was last updated. |
scopes | string The scope of the token, such as impersonation . |
impersonationuserid | string The user ID of the impersonating user. |
impersonationiamid | string The IAM ID of the impersonating user. |
Request example
This example request will return information on the access token in the payload.
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/token
Payload example
{
"token": "48983da*********85220837d"
}
Response example
{
"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
Endpoint
Method | Path | Purpose |
---|---|---|
GET | /bim/iam/{iamid}/user/{userid}/apikeys |
Get metadata for all of the user's API keys. |
Request Parameters
Attribute | Description | Required |
---|---|---|
iamid | string The IAM ID. |
Yes |
userid | string The user's username. |
Yes |
Response Parameters
Attribute | Description |
---|---|
keyid | integer The API key ID. |
created | timestamp The date the API key was created. |
project | 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 . |
lastUsed | timestamp The date the API key was last used. |
name | string The API key name. |
Request example
This example request will return information on the API keys of the user with the username john.doe@immuta.com
.
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
[
{
"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",