# Manage IAMs
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.
{% hint style="info" %}
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
{% endhint %}
## BIM workflow
Because the BIM endpoint encompasses groups, users, and authentications, there are three workflows.
### Users workflow
1. [Create a new user](#create-a-new-user).
2. [Manage your users](#manage-users).
3. [Review your users' information](#review-user-information).
4. [Delete a user](#delete-a-user).
### Groups workflow
1. [Create a new group](#create-a-new-group).
2. [Manage groups](#manage-groups).
3. [Search groups](#search-groups).
4. [Delete a group](#delete-a-group).
### Authenticate with the API workflow
1. [Create an API Key](#authenticate-a-user-and-create-a-project-api-key).
2. [Authenticate with an API key](#authenticate-with-an-api-key).
3. [View tokens and API key information](#view-tokens-and-api-keys).
4. [Remove an API key](#delete-an-api-key).
## Create a new user
`POST` `/bim/iam/bim/user`
Create a new BIM user.
#### 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. See [Immuta permissions and personas](/2024.2/people/immuta-users/reference-guides/personas-and-permissions.md) for a list of Immuta 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`.
```shell
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
```json
{
"iamid": "bim",
"userid": "charlie.doe@immuta.com",
"profile": {
"name": "Charlie Doe",
"email": "charlie.doe@immuta.com"
},
"permissions": []
}
```
### Response example
```json
{
"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](#authenticate-a-user-from-an-outside-iam). |
| POST | `/bim/iam/{iamid}/user/authenticate` | [Authenticate a user using their username and password and proxying it to the specified IAM service](#authenticate-user-with-username-and-password). |
| PUT | `/bim/iam/{iamid}/user/{userid}/profile` | [Update a specified user's profile](#update-a-user-profile). |
| DELETE | `/bim/iam/{iamid}/user/{userid}/permissions/{permission}` | [Remove the specified user's permission](#remove-a-users-permissions). |
| PUT | `/bim/iam/{iamid}/user/{userid}/permissions` | [Update the specified user's permissions](#update-a-users-permissions). |
| PUT | `/bim/iam/{iamid}/user/{userid}/password` | [Update the specified user's password](#update-a-users-password). |
| PUT | `/bim/iam/{iamid}/user/{userid}/disable/{disable}` | [Disable / enable the specified BIM user](#disable-or-enable-a-user). |
| POST | `/bim/syncUsers` | [Sync Users for external IAM](#sync-users-from-an-external-iam). |
| POST | `/iam/{iamId}/sync` | [Sync LDAP users with Immuta](#sync-ldap-users-with-immuta). |
| PUT | `/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue}` | [Update the specified user's attributes](#update-a-users-or-groups-attributes). |
| DELETE | `/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value}` | [Remove an attribute from the specified group or user](#remove-a-user-or-groups-attribute). |
| POST | `/bim/iam/bim/user/{userid}/clone` | [Clones the provided user to create multiple additional user accounts](#clone-user). |
### 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 |
| --------- | -------------------- | -------- |
| iamid | `string` The IAM ID. | **Yes** |
#### Request example
This example request
```shell
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 |
| --------- | -------------------- | -------- |
| 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.
```shell
curl \
--request POST \
--header "Content-Type: application/json" \
--data @example-payload.json \
https://demo.immuta.com/bim/iam/bim/user/authenticate
```
**Payload example**
```json
{
"username": "demo.user@immuta.com",
"password": "********"
}
```
#### Response example
```json
{
"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 |
| --------- | ----------------------------- | -------- |
| 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 |
| email | `string` The user email. | No |
| phone | `string` The user phone number. | No |
| sqlUser | `string` The user's SQL username. | No |
| about | `string` Details about the user to be displayed on their profile. | No |
| location | `string` The user's location. | No |
| organization | `string` The user's organization. | No |
| position | `string` The user's position. | No |
| externalUserIds | `array` A list of the user's external usernames for `hdfsUser`, `databricksUser`, `snowflakeUser`, `prestoUser`, `asaUser`, and `redshiftUser`. | No |
| preferences | `array` | No |
| scim | `array` | No |
#### 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`.
```shell
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**
```json
{
"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
```json
{
"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 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| iamid | `string` The IAM ID. | **Yes** |
| userid | `string` The user's username. | **Yes** |
| permission | `string` The permission to remove. See [Immuta permissions and personas](/2024.2/people/immuta-users/reference-guides/personas-and-permissions.md#permissions) 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`.
```shell
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
```json
{
"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 |
| --------- | ----------------------------- | -------- |
| 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](/2024.2/people/immuta-users/reference-guides/personas-and-permissions.md#permissions) 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`.
```shell
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**
```json
[
"CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT", "CREATE_DATA_SOURCE"
]
```
#### Response example
```json
{
"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 |
| --------- | ----------------------------- | -------- |
| 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`.
```shell
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**
```json
{
"originalPassword": "old********",
"password": "new********"
}
```
#### Response example
```json
{
"success": true
}
```
### Disable or enable a user
`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`.
```shell
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
```json
{
"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 |
| --------- | ----------------------------- | -------- |
| iamid | `string` The external IAM ID. | **Yes** |
#### Request example
This example request will sync the users from the specified external IAM with Immuta.
```shell
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/syncUsers
```
**Payload example**
```json
{
"iamid": "ldap"
}
```
### Sync LDAP users with Immuta
`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.
```shell
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**
```json
{
"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=)",
"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
```json
{
"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 |
| -------------- | ---------------------------------------------------------------------------------------- | -------- |
| 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`.
```shell
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
```json
{
"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 |
| --------- | -------------------------------------------------------------------------------------------------- | -------- |
| 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`.
```shell
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
```json
{
"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
{% hint style="warning" %}
**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.
{% endhint %}
`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 |
| --------- | -------------------------------------- | -------- |
| email | `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`.
```shell
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
```json
[
"john.doe@demo.com"
]
```
#### Response example
```json
{
"failedEmails": []
}
```
## Review user information
| Method | Path | Purpose |
| ------ | ---------------------------------------- | ---------------------------------------------------------------------------------- |
| GET | `/bim/iam` | [Get a listing of configured IAM services](#search-all-iams). |
| GET | `/bim/user` | [Administrative search over the aggregated view of all users](#search-all-users). |
| GET | `/bim/rpc/user/current` | [Get the currently logged in user's information](#view-current-users-information). |
| GET | `/bim/iam/{iamid}/user/{id}` | [Get the specified user's aggregated view](#view-a-users-information). |
| GET | `/bim/iam/{iamid}/user/{userid}/profile` | [Get the specified user's profile](#view-a-user-profile). |
| GET | `/bim/iam/{iamid}/user/{userid}/groups` | [Get the specified user's list of groups](#view-a-users-groups). |
### Search all IAMs
`GET` `/bim/iam`
Get a listing of configured IAM services.
#### 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.
```shell
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam
```
#### Response example
```json
[
{
"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 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- |
| 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 |
| email | `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. *The following details are excluded from the response if the requesting user does not have the `USER_ADMIN` Immuta permission: `bimAuthorizations`, `iamAuthorizations`, and `authorizations`.* |
| 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. *This attribute is excluded from the response if the requesting user does not have the `USER_ADMIN` Immuta permission.* |
| iamAuthorizations | `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.* |
| authorizations | `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.* |
| 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.
```shell
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
```json
{
"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 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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.
```shell
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/rpc/user/current
```
#### Response example
```json
{
"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 |
| --------- | ---------------------- | -------- |
| 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`.
```shell
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/2
```
#### Response example
```json
{
"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 |
| --------- | ---------------------- | -------- |
| iamid | `string` The IAM ID. | **Yes** |
| id | `integer` The user ID. | **Yes** |
#### Response parameters
| Attribute | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------- |
| name | `string` The user's name. |
| email | `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`.
```shell
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/user/2/profile
```
#### Response example
```json
{
"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 |
| --------- | ----------------------------- | -------- |
| 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`.
```shell
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
```json
[
{
"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 |
| --------- | ----------------------------- | -------- |
| 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`.
```shell
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
```json
{
"userid": "charlie.doe@immuta.com",
"iamid": "bim"
}
```
## Create a new group
`POST` `/bim/group`
Create a new group.
#### Payload parameters
| Attribute | Description | Required |
| ----------- | ------------------------------------- | -------- |
| iamid | `string` The IAM ID. | **Yes** |
| name | `string` The new group name. | **Yes** |
| email | `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. |
| email | `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`.
```shell
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/group
```
#### Payload example
```json
{
"iamid": "bim",
"name": "API Group"
}
```
### Response example
```json
{
"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](#update-a-group). |
| DELETE | `/bim/group/{groupId}/user/{groupuserid}` | [Remove a user from a group](#remove-a-user-from-a-group). |
| POST | `/bim/group/{groupId}/user` | [Add a new user to a group](#add-a-user-to-a-group). |
| PUT | `/bim/iam/{iamid}/group/{groupid}/authorizations` | [Update the specified group's authorizations](#update-a-groups-attributes). |
### Update a group
`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 |
| email | `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. |
| email | `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.
```shell
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**
```json
{
"name": "API Group #2",
"description": "This group was edited through the API"
}
```
#### Response example
```json
{
"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 |
| ----------- | ------------------------------ | -------- |
| groupId | `integer` The group ID. | **Yes** |
| groupuserid | `integer` The user's group ID. | **Yes** |
#### Request example
```shell
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 |
| --------- | ----------------------- | -------- |
| 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`.
```shell
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**
```json
{
"userid": "tom.jones@immuta.com",
"iamid": "bim"
}
```
#### Response example
```json
{
"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 |
| -------------- | ----------------------------- | -------- |
| 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. |
| email | `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`.
```shell
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
```json
{
"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](#search-all-groups-from-all-iams). |
| GET | `/bim/group/{groupId}` | [Get the specified group](#search-a-specific-group). |
| GET | `/bim/group/{groupId}/user` | [Get group users](#search-a-groups-users). |
### Search all groups from all IAMs
`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`, `createdAt`, and `updatedAt` values. *`authorizations` is excluded from the response if the requesting user does not have the `USER_ADMIN` Immuta permission.* |
| id | `integer` The group ID. |
| iamid | `string` The IAM ID. |
| name | `string` The name of the group. |
| email | `string` The group email. |
| authorizations | `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.* |
| 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.
```shell
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group?size=25&sortOrder=asc
```
#### Response example
```json
{
"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 |
| --------- | ------------------------------ | -------- |
| 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. |
| email | `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`.
```shell
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group/2
```
#### Response example
```json
{
"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 |
| --------- | ---------------------------------------------------------------------------------------------------------------- | -------- |
| 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`.
```shell
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/group/2/user
```
#### Response example
```json
{
"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 |
| --------- | ----------------------- | -------- |
| groupId | `integer` The group ID. | **Yes** |
### Request example
This request will delete the group with the ID `3`.
```shell
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 |
| --------- | ------------------------------------------------ | -------- |
| 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.
```shell
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/apikey
```
#### Payload example
```json
{
"projectId": 1,
"name": "My Project API Key"
}
```
### Response example
```json
{
"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](#authenticate-a-user-with-an-api-key). |
| POST | `/bim/apikey/impersonate` | [Impersonate another user using an API key](#impersonate-a-user-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
| 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.
```shell
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**
```json
{
"apikey": "100874dyour-api-key-79aa38bbfe0e8c787"
}
```
#### Response example
```json
{
"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 |
| --------- | --------------------------------------------------------------------------- |
| 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`.
```shell
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**
```json
{
"apikey": "requesting-users-api-key",
"userid": "user1@example.com",
"iamid": "bim"
}
```
#### Response example
```json
{
"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](#view-token-information). |
| GET | `/bim/iam/{iamid}/user/{userid}/apikeys` | [Get metadata for all of the user's API Keys](#view-a-users-api-keys). |
### View token information
`POST` `/bim/token`
Get information for a given token, should it exist.
#### 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.
```shell
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/token
```
**Payload example**
```json
{
"token": "48983da*********85220837d"
}
```
#### Response example
```json
{
"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 |
| --------- | ----------------------------- | -------- |
| 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`.
```shell
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
```json
[
{
"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 |
| --------- | ------------------------- | -------- |
| keyid | `integer` The API key ID. | **Yes** |
#### Response parameters
| Attribute | Description |
| ------------- | --------------------------------------- |
| revokedTokens | `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.
```shell
curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/apikey/323
```
### Response example
```json
{
"revokedTokens": 1
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://documentation.immuta.com/2024.2/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.