# 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.
**Required Immuta permission**: `USER_ADMIN`
#### 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](https://documentation.immuta.com/saas/configuration/people/users-index/reference-guides/personas-and-permissions#permissions) 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`.
```bash
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_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 |
| ------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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). |
| DELETE | `/bim/iam/{iamid}/authorizations/{key}/{value}` | [Remove the specified attribute from all groups and users](#remove-the-specified-attribute-from-all-users) |
### 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.
```bash
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.
**Requirement**: `USER_ADMIN` Immuta permission or it must be your user 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`.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### 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](https://documentation.immuta.com/saas/configuration/people/users-index/reference-guides/personas-and-permissions#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_PROJECT` from the user with the username `john.doe@immuta.com`.
```bash
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_PROJECT
```
#### Response example
```json
{
"id": 3,
"iamid": "bim",
"userid": "john.doe@immuta.com",
"bimAuthorizations": null,
"iamAuthorizations": null,
"authorizations": {},
"permissions": [],
"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.
**Required Immuta permission**: `USER_ADMIN`
#### 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](https://documentation.immuta.com/saas/configuration/people/users-index/reference-guides/personas-and-permissions#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 the permissions of the user with the username `charlie.doe@immuta.com` to `CREATE_PROJECT` and `CREATE_DATA_SOURCE`.
```bash
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_PROJECT", "CREATE_DATA_SOURCE"
]
```
#### Response example
```json
{
"id": 18,
"iamid": "bim",
"userid": "charlie.doe@immuta.com",
"bimAuthorizations": null,
"iamAuthorizations": null,
"authorizations": {},
"permissions": [
"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.
**Requirement**: `USER_ADMIN` Immuta permission or it must be your profile.
#### 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`.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### 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 disable the user with the username `jane.doe@immuta.com`.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### 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.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### 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 | `array` The set of actions that this IAM integration supports to determine which sync or management operations Immuta is allowed to execute for this IAM. | 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.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### 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`.
```bash
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_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.
**Required Immuta permission**: `USER_ADMIN`
#### 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`.
```bash
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_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.
**Required Immuta permission**: `USER_ADMIN`
#### 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`.
```bash
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": []
}
```
### Remove the specified attribute from all users
`DELETE` `/bim/iam/{iamid}/authorizations/{key}/{value}`
Removes the specified authorization from all groups and users.
**Required Immuta permission**: `USER_ADMIN`
#### Request parameters
| Attribute | Description | Required |
| --------- | --------------------------------------------------------------------------------- | -------- |
| iamid | `string` The ID for the IAM the attribute is in. Use `bim` for Immuta attributes. | **Yes** |
| key | `string` The attribute key to remove. | **Yes** |
| value | `string` The attribute value to remove. | No |
#### Response parameters
None
#### Request example
This example request will delete the attribute `attr.new` from all users and groups in Immuta.
```bash
curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/iam/bim/authorizations/attr/new
```
## 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). |
| POST | `/bim/user/search` | [Administrative search over the aggregated view of all users based on specific user details](#search-all-users-by-details). |
### 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.
```bash
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`
Search 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 by Immuta. | No |
| excludeAdminAndGovernor | `boolean` If `true`, users with the admin and governor permissions 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.
```bash
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 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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`, `entitlements`, `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. |
| systemGenerated | `boolean` If `true`, the user is a system generated user. |
| hasLogin | `boolean` If `true`, the user has logged into Immuta. |
| groups | `metadata` Information on the user's groups. |
| updatedAt | `timestamp` The date of the last time the user's information was updated. |
| lastExternalRefresh | `timestamp` The date of the last time the user's information was updated from an external IAM. |
| collectionPermissions | `object` Details on the user's permissions within domains. |
| isDataSourceOwner | `boolean` If `true`, the user is an owner of at least one data source. |
#### Request example
This request will return information on the user that is logged in.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/rpc/user/current
```
#### Response example
```json
{
"hasLogin": true,
"profile": {
"name": "Jane Doe",
"email": "jane.doe@immuta.com",
"phone": null,
"about": null,
"location": null,
"organization": null,
"position": null,
"preferences": {
"sortProjectState": {},
"tabProjectState": 0,
"sortProjectDataSourceState": {},
"currentProject": null,
"notifications": {
"email": false
}
},
"externalUserIds": {
"databricksUserObject": {
"id": null,
"type": "NONE"
}
},
"scim": null,
"entitlementHash": {
"type": "Buffer",
"data": [
56,
51
]
},
"entitlementJson": {
"authorizations": {
"attr": [
"new"
]
},
"groups": [
"Test"
]
},
"systemGenerated": false,
"id": 117,
"createdAt": "2024-07-03T14:59:02.142Z",
"updatedAt": "2025-10-08T14:47:25.263Z"
},
"permissions": [
"APPLICATION_ADMIN",
"GOVERNANCE"
],
"iamid": "bim",
"userid": "jane.doe@immuta.com",
"authorizations": {},
"updatedAt": "2025-10-08T14:47:25.273Z",
"systemGenerated": false,
"disabled": false,
"lastLogin": "2025-12-04T18:20:55.275Z",
"lastExternalRefresh": "2025-12-04T18:20:55.275Z",
"bimAuthorizations": null,
"iamAuthorizations": null,
"collectionPermissions": {
"c959079a-4448-4b9c-b6b1-4fd8dd7b3dd1": [
{
"collectionId": "c959079a-4448-4b9c-b6b1-4fd8dd7b3dd1",
"permission": "Audit Activity",
"profileId": 117,
"createdAt": "2025-02-27T19:05:46.304Z",
"id": "a9076398-cb25-4cf4-9010-8e50b7d634d9",
"groupId": null
}
],
"d62faf38-8d3a-478b-839b-ad79c5c1ffff": [
{
"collectionId": "d62faf38-8d3a-478b-839b-ad79c5c1ffff",
"permission": "Audit Activity",
"profileId": 117,
"createdAt": "2025-02-27T19:15:15.964Z",
"id": "b96fea6b-c7d7-476a-95af-2715f29df9bb",
"groupId": null
},
{
"collectionId": "d62faf38-8d3a-478b-839b-ad79c5c1ffff",
"permission": "Manage Data Products",
"profileId": 117,
"createdAt": "2025-02-27T19:15:15.964Z",
"id": "5b5514a9-5dce-4212-84a5-c64e21c859aa",
"groupId": null
}
]
},
"groups": [
1
],
"isDataSourceOwner": true
}
```
### View a user's information
`GET` `/bim/iam/{iamid}/user/{id}`
Gets the specified user's aggregated view.
**Required Immuta permission**: `USER_ADMIN` or `AUDIT`
#### 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`.
```bash
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_PROJECT",
"CREATE_DATA_SOURCE",
"USER_ADMIN",
"APPLICATION_ADMIN",
"AUDIT",
"GOVERNANCE",
"IMPERSONATE_HDFS_USER",
"CREATE_S3_DATASOURCE",
"FETCH_POLICY_INFO",
"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** |
| userid | `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`.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### 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 unique membership group ID. |
#### Request example
This example request will return information on the groups of the user with the username `john.doe@immuta.com`.
```bash
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
}
]
```
### Search all users by details
`POST` `/bim/user/search`
Administrative search over the aggregated view of all users based on specific user details.
**Required Immuta permission**: `USER_ADMIN`
#### Payload 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 |
| email | `string` A partial email address to match against user email addresses. | No |
| userid | `string` A partial ID to match against user IDs. | No |
| iamid | `array[string]` Optionally provide the IAM to filter the users. | No |
| excludeSystemGenerated | `boolean` If `true`, the results will exclude accounts automatically created by Immuta. | No |
| excludeAdminAndGovernor | `boolean` If `true`, users with the admin and governor permissions 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 |
| includeEnabled | `boolean` If `true`, the results will include enabled users. | No |
| sortField | `string` The field to sort results on. **The default is `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 |
| offset | `integer` Offset to start returning values. | No |
| permission | `string` A permission to filter the users by. | No |
| domainPermission | `string` A domain permission to filter the users by. | No |
| domainId | `string` A domain ID to filter the users by. | No |
| profileIds | `array[integer]` Filters results to return users with the specified profile IDs. | No |
| globalUserIds | `array[string]` Filters results to return users with the specified global user IDs. | No |
| groupNames | `array[string]` Filters results to return users that belong to the specified groups by name. | No |
| groupIds | `array[integer]` Filters results to return users that belong to the specified groups by ID. | No |
| userAttributes | `array[object]` Filters results to return users with the specified attributes. Each object should contain `key` and `value` properties. | 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 `authentication`, `createdAt`, `disabled`, `iamid`, `id`, `lastExternalRefresh`, `lastLogin`, `permissions`, `systemGenerated`, `updatedAt`, `userid`, `globalUserId`, `profile`, `authorizations`, and `bimAuthorizations` values. |
| id | `integer` The user ID. |
| authentication | `integer` The user's authentication ID. |
| iamid | `string` The ID of the IAM the user is connected to. |
| userid | `string` The user's username. |
| globalUserId | `string` The user's global unique identifier. |
| authorizations | `metadata` Details on the user's attributes. |
| bimAuthorizations | `array` The attributes and groups given to the user in Immuta. |
| permissions | `string` A list of the user's permissions. |
| profile | `metadata` Details on the user, including `name`, `email`, `externalUserIds`, `systemGenerated`, `id`, `createdAt`, and `updatedAt` values. |
| lastLogin | `timestamp` The date of the user's last Immuta login. |
| lastExternalRefresh | `timestamp` The date of the last time the user's information was updated from an external IAM. |
| disabled | `boolean` If `true`, the user has been disabled. |
| systemGenerated | `boolean` If `true`, the user is a system generated user. |
| 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 example request will return information on the users with "arthur" in their name.
```bash
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://demo.immuta.com/bim/user/search
```
#### Payload example
```json
{
"name":"arthur"
}
```
#### Response example
```json
{
"hits": [
{
"authentication": 10,
"createdAt": "2023-05-18T15:55:43.331Z",
"disabled": false,
"iamid": "bim",
"id": 9,
"lastExternalRefresh": "2025-12-01T15:37:36.890Z",
"lastLogin": "2025-12-01T15:37:36.890Z",
"permissions": [
"CREATE_PROJECT",
"USER_ADMIN",
"APPLICATION_ADMIN",
"CREATE_DATA_SOURCE",
"AUDIT",
"GOVERNANCE",
"IMPERSONATE_HDFS_USER",
"CREATE_S3_DATASOURCE_WITH_INSTANCE_ROLE",
"FETCH_POLICY_INFO",
"IMPERSONATE_USER",
"PROJECT_MANAGEMENT",
"CREATE_S3_DATASOURCE"
],
"systemGenerated": false,
"updatedAt": "2025-12-04T17:58:52.647Z",
"userid": "arthur.1@immuta.com",
"globalUserId": "333a33d4-504a-4f4e-b553-555b912ca3df",
"profile": {
"createdAt": "2023-05-18T15:55:42.555Z",
"email": "arthur.1@immuta.com",
"externalUserIds": {},
"id": 7,
"name": "Arthur 1",
"systemGenerated": false,
"updatedAt": "2025-12-04T17:58:52.636Z"
},
"authorizations": {
"attr": [
"value",
"val3"
]
},
"bimAuthorizations": {
"attr": [
"value",
"val3"
]
}
},
{
"authentication": 131,
"createdAt": "2025-05-07T20:17:34.397Z",
"disabled": false,
"iamid": "bim",
"id": 131,
"lastExternalRefresh": "2025-05-10T17:28:07.132Z",
"lastLogin": "2025-05-10T17:28:07.132Z",
"permissions": [
"CREATE_DATA_SOURCE",
"CREATE_PROJECT",
"USER_ADMIN",
"APPLICATION_ADMIN",
"AUDIT",
"GOVERNANCE",
"IMPERSONATE_HDFS_USER",
"CREATE_S3_DATASOURCE_WITH_INSTANCE_ROLE",
"FETCH_POLICY_INFO",
"IMPERSONATE_USER",
"PROJECT_MANAGEMENT",
"CREATE_S3_DATASOURCE"
],
"systemGenerated": false,
"updatedAt": "2025-05-07T20:19:23.710Z",
"userid": "arthur.1+disco@immuta.com",
"globalUserId": "31f585e9-0488-4c8e-a62b-fe311627b9b2",
"profile": {
"createdAt": "2025-05-07T20:17:34.397Z",
"email": "arthur.1+disco@immuta.com",
"externalUserIds": {
"databricksUserObject": {
"id": null,
"type": "NONE"
}
},
"id": 131,
"name": "arthur 1 another account",
"systemGenerated": false,
"updatedAt": "2025-07-23T20:16:59.013Z"
},
"authorizations": {}
},
{
"authentication": 132,
"createdAt": "2025-05-10T14:56:21.137Z",
"disabled": false,
"iamid": "bim",
"id": 132,
"lastExternalRefresh": "2025-09-25T17:58:26.588Z",
"lastLogin": "2025-09-25T17:58:26.588Z",
"permissions": [
"CREATE_DATA_SOURCE",
"CREATE_PROJECT",
"USER_ADMIN",
"APPLICATION_ADMIN",
"AUDIT",
"GOVERNANCE",
"IMPERSONATE_HDFS_USER",
"CREATE_S3_DATASOURCE_WITH_INSTANCE_ROLE",
"FETCH_POLICY_INFO",
"IMPERSONATE_USER",
"PROJECT_MANAGEMENT",
"CREATE_S3_DATASOURCE"
],
"systemGenerated": false,
"updatedAt": "2025-05-10T14:58:02.857Z",
"userid": "arthur.1+secret@immuta.com",
"globalUserId": "4f6bd06f-c491-41f2-a9e4-b6c8437cfb39",
"profile": {
"createdAt": "2025-05-10T14:56:21.137Z",
"email": "arthur.1+secret@immuta.com",
"externalUserIds": {
"databricksUserObject": {
"id": null,
"type": "NONE"
}
},
"id": 132,
"name": "Arthur's Secret Identifity",
"systemGenerated": false,
"updatedAt": "2025-07-23T20:16:59.011Z"
},
"authorizations": {}
}
],
"count": "3"
}
```
## Create a new group
`POST` `/bim/group`
Create a new group.
**Required Immuta permission**: `USER_ADMIN`
#### 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`.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### 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.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### Request parameters
| Attribute | Description | Required |
| ----------- | ------------------------------------------------ | -------- |
| groupId | `integer` The group ID. | **Yes** |
| groupuserid | `integer` The user's unique membership group ID. | **Yes** |
#### Request example
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### 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 unique membership 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`.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### 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`.
```bash
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 | `array[string]` Optionally provide IAMs to filter the groups returned. | 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. |
| 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.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### 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`.
```bash
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
If the requesting user does not have the `USER_ADMIN` permission, only usernames (`profile.name`) will be returned in the response.
| 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 user's unique membership 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`.
```bash
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.
**Required Immuta permission**: `USER_ADMIN`
#### Query parameters
| Attribute | Description | Required |
| --------- | ----------------------- | -------- |
| groupId | `integer` The group ID. | **Yes** |
### Request example
This request will delete the group with the ID `3`.
```bash
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.
**Requirement**: You must be a member of the project.
#### 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.
```bash
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.
```bash
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.
**Required Immuta permission**: `IMPERSONATE_USER`
#### 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`.
```bash
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.
```bash
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.
**Requirement**: `USER_ADMIN` permission or they must be your 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`.
```bash
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.
**Requirement**: You must have created the 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.
```bash
curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://demo.immuta.com/bim/apikey/323
```
### Response example
```json
{
"revokedTokens": 1
}
```