# 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 as a user](#authenticate-a-user-and-create-a-project-api-key).
2. [Create an API key for an agent](#create-an-agent-identity-api-key).
3. [Authenticate with an API key](#authenticate-with-an-api-key).
4. [View tokens and API key information](#view-tokens-and-api-keys).
5. [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](/saas/configuration/people/users-index/reference-guides/personas-and-permissions.md#permissions) for a list of Immuta permissions. | No |
| type | `string` The type of new identity to create. Options include `user` and `agent`. | 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](/saas/configuration/people/users-index/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_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](/saas/configuration/people/users-index/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 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
}
```
## Create an agent identity API key
`POST` `/bim/iam/{iamid}/user/{userid}/apikeys`
Create an API key for an agent. The agent will use this API key to make requests to the Immuta API to vend and delete ephemeral roles.
**Requirement**: `USER_ADMIN` Immuta permission or own the agent
### Path parameters
| Parameter | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| iamid `string` | The unique identifier of your identity provider. If you created the agent in Immuta, this value is `bim`. |
| userid `string` | The unique identifier of the agent. You can get this ID [through the Immuta API](#search-all-users) and using the agent's name as a search filter. Or it is presented in the Agent table. |
### Body parameters
| Parameter | Description | Required or optional | Default |
| ----------------- | -------------------------------- | -------------------- | -------------------------- |
| name `string` | The name of the agent's API key. | Optional | - |
| expiration `date` | The date the API key expires. | Optional | `2070-01-01T00:00:00.000Z` |
### Response attributes
| Attribute | Description |
| ----------------- | --------------------------------- |
| apikey `string` | The agent's new API key. |
| keyid `integer` | A unique ID for the new API key. |
| name `string` | The name of the new API key. |
| expiration `date` | The date the API key will expire. |
### Example request
```bash
curl -X 'POST' \
'https://www.organization.immuta.com/bim/iam/bim/user/snowflake_agent/apikeys' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"name": "Marketing department agent API key",
"expiration": "2027-03-23"
}'
```
### Example response
```bash
{
"apikey": "4d69ba7c8e8a4207bac96dd8ba06a7eb",
"keyid": 7495,
"name": "Marketing department agent API key",
"expiration": "2027-03-23"
}
```
## 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
}
```
---
# 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/saas/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.