> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md). # Manage IAMs Understand the parameters and response schema of the bim endpoints Use the `bim` API to manage users, groups, identity and access management (IAM) services, API keys, and personal access tokens. Most endpoints require administrative 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 %} ## Endpoints and methods | Method | Endpoint | Description | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | **POST** | [`/bim/iam/bim/user`](#post-bim-iam-bim-user) | Create a BIM user. | | **POST** | [`/bim/iam/{iamid}/user/authenticate`](#post-bim-iam-iamid-user-authenticate) | Authenticate a user with an IAM service. | | **PUT** | [`/bim/iam/{iamid}/user/{userid}/profile`](#put-bim-iam-iamid-user-userid-profile) | Update a user's profile. | | **DELETE** | [`/bim/iam/{iamid}/user/{userid}/permissions/{permission}`](#delete-bim-iam-iamid-user-userid-permissions-permission) | Remove a user's permission. | | **PUT** | [`/bim/iam/{iamid}/user/{userid}/permissions`](#put-bim-iam-iamid-user-userid-permissions) | Replace a user's permissions. | | **PUT** | [`/bim/iam/{iamid}/user/{userid}/password`](#put-bim-iam-iamid-user-userid-password) | Update a user's password. | | **PUT** | [`/bim/iam/{iamid}/user/{userid}/disable/{disable}`](#put-bim-iam-iamid-user-userid-disable-disable) | Enable or disable a BIM user. | | **POST** | [`/bim/syncUsers`](#post-bim-syncusers) | Synchronize users from an external IAM. | | **POST** | [`/iam/{iamId}/sync`](#post-iam-iamid-sync) | Synchronize LDAP users. | | **PUT** | [`/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue}`](#put-bim-iam-iamid-modeltype-modelid-authorizations-attributename-attributevalue) | Add a user or group attribute. | | **DELETE** | [`/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value}`](#delete-bim-iam-iamid-modeltype-modelid-authorizations-key-value) | Remove a user or group attribute. | | **POST** | [`/bim/iam/bim/user/{userid}/clone`](#post-bim-iam-bim-user-userid-clone) | Clone a BIM user. | | **DELETE** | [`/bim/iam/{iamid}/authorizations/{key}/{value}`](#delete-bim-iam-iamid-authorizations-key-value) | Remove an attribute from all users and groups. | | **GET** | [`/bim/iam`](#get-bim-iam) | List configured IAM services. | | **GET** | [`/bim/user`](#get-bim-user) | Search users. | | **GET** | [`/bim/rpc/user/current`](#get-bim-rpc-user-current) | Get the current user's information. | | **GET** | [`/bim/iam/{iamid}/user/{id}`](#get-bim-iam-iamid-user-id) | Get a user's aggregated view. | | **GET** | [`/bim/iam/{iamid}/user/{userid}/profile`](#get-bim-iam-iamid-user-userid-profile) | Get a user's profile. | | **GET** | [`/bim/iam/{iamid}/user/{userid}/groups`](#get-bim-iam-iamid-user-userid-groups) | List a user's groups. | | **POST** | [`/bim/user/search`](#post-bim-user-search) | Search users by details. | | **POST** | [`/bim/group`](#post-bim-group) | Create a group. | | **PUT** | [`/bim/group/{groupId}`](#put-bim-group-groupid) | Update a group. | | **DELETE** | [`/bim/group/{groupId}/user/{groupuserid}`](#delete-bim-group-groupid-user-groupuserid) | Remove a user from a group. | | **POST** | [`/bim/group/{groupId}/user`](#post-bim-group-groupid-user) | Add a user to a group. | | **PUT** | [`/bim/iam/{iamid}/group/{groupId}/authorizations/{attributeName}/{attributeValue}`](#put-bim-iam-iamid-group-groupid-authorizations-attributename-attributevalue) | Add a group attribute. | | **GET** | [`/bim/group`](#get-bim-group) | List groups. | | **GET** | [`/bim/group/{groupId}`](#get-bim-group-groupid) | Get a group. | | **GET** | [`/bim/group/{groupId}/user`](#get-bim-group-groupid-user) | List group users. | | **DELETE** | [`/bim/group/{groupId}`](#delete-bim-group-groupid) | Delete a group. | | **POST** | [`/bim/apikey`](#post-bim-apikey) | Create an API key for the current user. | | **POST** | [`/bim/iam/{iamId}/user/{userId}/apikeys`](#post-bim-iam-iamid-user-userid-apikeys) | Create an agent API key. | | **POST** | [`/bim/iam/{iamId}/agent/{agentId}/tokens`](#post-bim-iam-iamid-agent-agentid-tokens) | Create an agent personal access token. | | **GET** | [`/bim/iam/{iamId}/agent/{agentId}/tokens`](#get-bim-iam-iamid-agent-agentid-tokens) | List agent personal access tokens. | | **DELETE** | [`/bim/iam/{iamId}/agent/{agentId}/tokens/{tokenId}`](#delete-bim-iam-iamid-agent-agentid-tokens-tokenid) | Delete an agent personal access token. | | **POST** | [`/bim/apikey/system`](#post-bim-apikey-system) | Create or return a system API key. | | **DELETE** | [`/bim/apikey/{keyid}`](#delete-bim-apikey-keyid) | Delete the current user's API key. | | **DELETE** | [`/bim/apikey/system/{keyid}`](#delete-bim-apikey-system-keyid) | Delete a system API key. | | **POST** | [`/bim/apikey/authenticate`](#post-bim-apikey-authenticate) | Authenticate with an API key. | | **POST** | [`/bim/apikey/impersonate`](#post-bim-apikey-impersonate) | Impersonate a user with an API key. | | **POST** | [`/bim/token`](#post-bim-token) | Get token information. | | **GET** | [`/bim/iam/{iamid}/user/{userid}/apikeys`](#get-bim-iam-iamid-user-userid-apikeys) | List a user's API keys. | ## `POST` `/bim/iam/bim/user` Create a new BIM user. **Required Immuta permission**: `USER_ADMIN` ```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** ```json { "iamid": "bim", "userid": "charlie.doe@immuta.com", "profile": { "name": "Charlie Doe", "email": "charlie.doe@immuta.com" }, "permissions": [] } ``` ### Payload parameters | Parameter | Description | Required or optional | Accepted values | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------- | | **iamid** `string` | The IAM ID. | Required | - | | **userid** `string` | The new user's username. | Required | - | | **password** `string` | The new user's password. | Optional | - | | **profile** `array` | Information on the new user's name and email. | Optional | - | | **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. | Optional | - | | **type** `string` | The type of new identity to create. | Optional | | ### Response Returns an object containing `newUser` ([detailed user object](#detailed-user-object)), `newUserLink`, `emailFailed`, and `emailSent`. ```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 } ``` ## `POST` `/bim/iam/{iamid}/user/authenticate` Authenticate a user using their username and password and proxying it to the specified IAM service. ```bash curl \ --request POST \ --header "Content-Type: application/json" \ --data @example-payload.json \ https://demo.immuta.com/bim/iam/bim/user/authenticate ``` **Payload** ```json { "username": "demo.user@immuta.com", "password": "********" } ``` ### Request parameter | Parameter | Description | Required or optional | | ------------------ | ----------- | -------------------- | | **iamid** `string` | The IAM ID. | Required | ### Payload parameters | Parameter | Description | Required or optional | | --------------------- | -------------------------------------------------------- | -------------------- | | **username** `string` | The user's username for the IAM dictated in the request. | Required | | **password** `string` | The user's password for the IAM dictated in the request. | Required | ### Response ```json { "authenticated": true, "token": "6913229***********0d3da", "tokenExpiration": "2021-09-29T19:12:51.467Z" } ``` | 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. | ## `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. ```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** ```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" } ``` ### Request parameters | Parameter | Description | Required or optional | | ------------------- | -------------------- | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **userid** `string` | The user's username. | Required | ### Payload parameters | Parameter | Description | Required or optional | | --------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------- | | **iamid** `string` | The IAM ID. | Optional | | **userid** `string` | The user's username. | Optional | | **email** `string` | The user email. | Optional | | **phone** `string` | The user phone number. | Optional | | **sqlUser** `string` | The user's SQL username. | Optional | | **about** `string` | Details about the user to be displayed on their profile. | Optional | | **location** `string` | The user's location. | Optional | | **organization** `string` | The user's organization. | Optional | | **position** `string` | The user's position. | Optional | | **externalUserIds** `array` | A list of the user's external usernames for supported technologies. | Optional | | **preferences** `object` | User preferences for the Immuta UI including sort settings, notification settings, and current project. | Optional | | **scim** `object` | User profile metadata from the external IAM, if available. | Optional | ### Response Returns a [user profile object](#user-profile-attributes). ```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 } ``` ## `DELETE` `/bim/iam/{iamid}/user/{userid}/permissions/{permission}` Remove the specified user's permission. **Required Immuta permission**: `USER_ADMIN` ```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 ``` ### Request parameters | Parameter | Description | Required or optional | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **userid** `string` | The user's username. | Required | | **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. | Required | ### Response Returns the updated [user object](#user-object-attributes). ## `PUT` `/bim/iam/{iamid}/user/{userid}/permissions` Update the specified user's permission. **Required Immuta permission**: `USER_ADMIN` ```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** ```json [ "CREATE_PROJECT", "CREATE_DATA_SOURCE" ] ``` ### Request parameters | Parameter | Description | Required or optional | | ------------------- | -------------------- | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **userid** `string` | The user's username. | Required | ### Payload parameter | Parameter | Description | Required or optional | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | | **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. | Required | ### Response Returns the updated [user object](#user-object-attributes). ## `PUT` `/bim/iam/{iamid}/user/{userid}/password` Update the specified user's password. **Requirement**: `USER_ADMIN` Immuta permission or it must be your profile. ```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** ```json { "originalPassword": "old********", "password": "new********" } ``` ### Request parameters | Parameters | Description | Required or optional | | ------------------- | -------------------- | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **userid** `string` | The user's username. | Required | ### Payload parameters | Parameters | Description | Required or optional | | ----------------------------- | ------------------------ | -------------------- | | **originalPassword** `string` | The user's old password. | Required | | **password** `string` | The user's new password. | Required | ### Response Will return `success: true` if the user's password has been successfully changed. ## `PUT` `/bim/iam/{iamid}/user/{userid}/disable/{disable}` Disable or enable the specified BIM user. **Required Immuta permission**: `USER_ADMIN` ```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 ``` ### Request parameters | Parameter | Description | Required or optional | | --------------------- | ------------------------------------- | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **userid** `string` | The user's username. | Required | | **disable** `boolean` | If `true`, the user will be disabled. | Required | ### Response ```json { "userid": "jane.doe@immuta.com", "disabled": true } ``` | Attribute | Description | | ---------------------- | -------------------------------- | | **userid** `string` | The user's username. | | **disabled** `boolean` | If `true`, the user is disabled. | ## `POST` `/bim/syncUsers` Sync users from an external IAM. To sync LDAP users, use the [`/iam/{iamId}/sync` endpoint](#post-iam-iamid-sync). **Required Immuta permission**: `USER_ADMIN` ```bash curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ --data @example-payload.json \ https://demo.immuta.com/bim/syncUsers ``` **Payload** ```json { "iamid": "ImmutaConnect" } ``` ### Payload parameter | Parameter | Description | Required or optional | | ------------------ | -------------------- | -------------------- | | **iamid** `string` | The external IAM ID. | Required | ### Response If successful, returns `200`. ## `POST` `/iam/{iamId}/sync` Sync LDAP users with Immuta. **Required Immuta permission**: `USER_ADMIN` ```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** ```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" } } ``` ### Request parameter | Parameter | Description | Required or optional | | ------------------ | -------------------- | -------------------- | | **iamId** `string` | The external IAM ID. | Required | ### Payload parameters | Parameter | Description | Required or optional | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | **dryRun** `boolean` | If `true`, no updates will actually be made. | Required | | **iamConfig** `array` | Details about the IAM configuration, including `authenticationOnly`, `credentials`, `defaultPermissions`, `displayName`, `id`, `ldapSync`, and `options`. | Optional | | **plugin** `string` | The type of plugin the IAM uses, `ldap`. | Optional | | **schema** `array` | Details about the IAM schema, including `group`, `profile`, `authorizations`, and `externalUserIds`. | Optional | | **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. | Optional | | **type** `string` | The type of IAM, `ldap`. | Optional | ### Response ```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 } ``` | 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. | ## `PUT` `/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue}` Update the specified user's attributes. **Required Immuta permission**: `USER_ADMIN` ```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 ``` ### Request parameters | Parameter | Description | Required or optional | Accepted values | | --------------------------- | -------------------------------------------- | -------------------- | -------------------------------------------------------------- | | **iamid** `string` | The IAM ID. | Required | - | | **modelType** `string` | The type of model the attribute is added to. | Required | | | **modelId** `string` | The user or group ID. | Required | - | | **attributeName** `string` | The attribute name. | Required | - | | **attributeValue** `string` | The attribute value. | Required | - | ### Response Returns the updated [user](#user-object-attributes) or [group object](#group-object-attributes). ## `DELETE` `/bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value}` Remove an attribute from the specified group or user. **Required Immuta permission**: `USER_ADMIN` ```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 ``` ### Request parameters | Parameter | Description | Required or optional | Accepted values | | ---------------------- | ------------------------------------------------------ | -------------------- | -------------------------------------------------------------- | | **iamid** `string` | The ID for the IAM the user or group is under. | Required | - | | **modelId** `string` | The user or group ID. | Required | - | | **modelType** `string` | The type of model the attribute is being removed from. | Required | | | **key** `string` | The attribute to remove. | Required | - | | **value** `string` | The attribute value to remove. | Optional | - | ### Response Returns the updated [user](#user-object-attributes) or [group object](#group-object-attributes). ## `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` ```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** ```json [ "john.doe@demo.com" ] ``` ### Request parameter | Parameter | Description | Required or optional | | ------------------- | -------------------- | -------------------- | | **userid** `string` | The user's username. | Required | ### Payload parameter | Attribute | Description | Required or optional | | ----------------- | ------------------------------ | -------------------- | | **email** `array` | The list of new users' emails. | Required | ### Response Will return a list of any emails that failed to become users. ```json { "failedEmails": [] } ``` ## `DELETE` `/bim/iam/{iamid}/authorizations/{key}/{value}` Removes the specified authorization from all groups and users. **Required Immuta permission**: `USER_ADMIN` ```bash curl \ --request DELETE \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://demo.immuta.com/bim/iam/bim/authorizations/attr/new ``` ### Request parameters | Parameter | Description | Required or optional | | ------------------ | ------------------------------------------------------------------------ | -------------------- | | **iamid** `string` | The ID for the IAM the attribute is in. Use `bim` for Immuta attributes. | Required | | **key** `string` | The attribute key to remove. | Required | | **value** `string` | The attribute value to remove. | Optional | ### Response If successful, returns `200`. ## `GET` `/bim/iam` Get a listing of configured IAM services. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://demo.immuta.com/bim/iam ``` ### Response ```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" } ] ``` | 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. | ## `GET` `/bim/user` Search all users. ```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 ``` ### Query parameters | Parameter | Description | Required or optional | Default values | Accepted values | | ------------------------------------- | ------------------------------------------------------------------------------------- | -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **size** `integer` | The maximum number of records to return. | Optional | `25` | - | | **name** `string` | A partial name to match against user names. | Optional | - | - | | **userid** `string` | A partial ID to match against user IDs. | Optional | - | - | | **email** `string` | A partial email address to match against user email addresses. | Optional | - | - | | **iamid** `string[]` | Optionally provide the IAM to filter the users. | Optional | - | - | | **profileIds** `string[]` | Filters results to return users with the specified profile IDs. | Optional | - | - | | **excludeSystemGenerated** `boolean` | If `true`, the results will exclude accounts automatically created by Immuta. | Optional | - | | | **excludeAdminAndGovernor** `boolean` | If `true`, users with the admin and governor permissions will be excluded. | Optional | - | | | **excludeDeletediams** `boolean` | If `true`, the results will exclude users for any IAMs that are no longer configured. | Optional | - | | | **excludebim** `boolean` | If `true`, users from the Immuta internal identity manager will be excluded. | Optional | - | | | **includeDisabled** `boolean` | If `true`, the results will include disabled users. | Optional | - | | | **offset** `integer` | Offset to start returning values. | Optional | - | - | | **sortField** `string` | The field to sort results on. | Optional | `username` | | | **sortOrder** `string` | The order that the results will be sorted in. | Optional | `asc` | | | **permission** `string` | A permission to filter the users by. | Optional | - | - | ### Response Returns a list of [detailed user objects](#detailed-user-object). ## `GET` `/bim/rpc/user/current` Get the currently logged in user's information. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://demo.immuta.com/bim/rpc/user/current ``` ### Response Returns a [detailed user object](#detailed-user-object). ## `GET` `/bim/iam/{iamid}/user/{id}` Gets the specified user's aggregated view. **Required Immuta permission**: `USER_ADMIN` or `AUDIT` ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://demo.immuta.com/bim/iam/bim/user/2 ``` ### Request parameters | Parameter | Description | Required or optional | | ------------------ | ------------ | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **id** `integer` | The user ID. | Required | ### Response Returns a [detailed user object](#detailed-user-object). ## `GET` `/bim/iam/{iamid}/user/{userid}/profile` Gets the specified user's profile. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://demo.immuta.com/bim/iam/bim/user/2/profile ``` ### Request parameters | Parameter | Description | Required or optional | | -------------------- | ------------ | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **userid** `integer` | The user ID. | Required | ### Response Returns a [user profile object](#user-profile-attributes). ## `GET` `/bim/iam/{iamid}/user/{userid}/groups` Get the specified user's list of groups. **Required Immuta permission**: `USER_ADMIN` ```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 ``` #### Request parameters | Parameter | Description | Required or optional | | ------------------- | -------------------- | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **userid** `string` | The user's username. | Required | ### Response ```json [ { "id": 2, "name": "API Group #2", "iamid": "bim", "groupUser": 6 } ] ``` | 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. | ## `POST` `/bim/user/search` Administrative search over the aggregated view of all users based on specific user details. **Required Immuta permission**: `USER_ADMIN` ```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** ```json { "name":"arthur" } ``` ### Payload parameters
ParameterDescriptionRequired or optionalDefault valuesAccepted values
size integerThe maximum number of records to return.Optional25-
name stringA partial name to match against user names.Optional--
email stringA partial email address to match against user email addresses.Optional--
userid stringA partial ID to match against user IDs.Optional--
iamid array[string]Optionally provide the IAM to filter the users.Optional--
excludeSystemGenerated booleanIf true, the results will exclude accounts automatically created by Immuta.Optional-
  • true
  • false
excludeAdminAndGovernor booleanIf true, users with the admin and governor permissions will be excluded.Optional-
  • true
  • false
excludeDeletedIams booleanIf true, the results will exclude users for any IAMs that are no longer configured.Optional-
  • true
  • false
excludeBIM booleanIf true, users from the Immuta internal identity manager will be excluded.Optional-
  • true
  • false
includeDisabled booleanIf true, the results will include disabled users.Optional-
  • true
  • false
includeEnabled booleanIf true, the results will include enabled users.Optional-
  • true
  • false
sortField stringThe field to sort results on.Optionalname
  • name
  • createdAt
  • iamid
  • email
sortOrder stringThe order that the results will be sorted in.Optionalasc
  • asc
  • desc
offset integerOffset to start returning values.Optional--
permission stringA permission to filter the users by.Optional--
domainPermission stringA domain permission to filter the users by.Optional--
domainId stringA domain ID to filter the users by.Optional--
profileIds array[integer]Filters results to return users with the specified profile IDs.Optional--
globalUserIds array[string]Filters results to return users with the specified global user IDs.Optional--
groupNames array[string]Filters results to return users that belong to the specified groups by name.Optional--
groupIds array[integer]Filters results to return users that belong to the specified groups by ID.Optional--
userAttributes array[object]Filters results to return users with the specified attributes. Each object should contain key and value properties.Optional
### Response Returns a list of [user objects](#user-object-attributes). ## `POST` `/bim/group` Create a new group. **Required Immuta permission**: `USER_ADMIN` ```bash curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ --data @example-payload.json \ https://demo.immuta.com/bim/group ``` **Payload** ```json { "iamid": "bim", "name": "API Group" } ``` ### Payload parameters | Parameters | Description | Required or optional | | ------------------------ | ---------------------------- | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **name** `string` | The new group name. | Required | | **email** `string` | The new group's email. | Optional | | **description** `string` | The new group's description. | Optional | ### Response Returns a [group object](#group-object-attributes). ```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" } ``` ## `PUT` `/bim/group/{groupId}` Update the specified group. **Required Immuta permission**: `USER_ADMIN` ```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** ```json { "name": "API Group #2", "description": "This group was edited through the API" } ``` ### Request parameter | Parameter | Description | Required or optional | | --------------------- | ------------- | -------------------- | | **groupId** `integer` | The group ID. | Required | ### Payload parameters | Parameters | Description | Required or optional | | ------------------------ | ---------------------------- | -------------------- | | **name** `string` | The group's new name. | Optional | | **email** `string` | The group's new email. | Optional | | **description** `string` | The group's new description. | Optional | ### Response Returns a [group object](#group-object-attributes). ## `DELETE` `/bim/group/{groupId}/user/{groupuserid}` Remove a user from a group. **Required Immuta permission**: `USER_ADMIN` ```bash curl \ --request DELETE \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://demo.immuta.com/bim/group/1/user/2 ``` ### Request parameters | Parameter | Description | Required or optional | | ------------------------- | -------------------------------------- | -------------------- | | **groupId** `integer` | The group ID. | Required | | **groupuserid** `integer` | The user's unique membership group ID. | Required | ### Response If successful, returns `204`. ## `POST` `/bim/group/{groupId}/user` Add a new user to a group. **Required Immuta permission**: `USER_ADMIN` ```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** ```json { "userid": "tom.jones@immuta.com", "iamid": "bim" } ``` ### Request parameter | Parameter | Description | Required or optional | | --------------------- | ------------- | -------------------- | | **groupId** `integer` | The group ID. | Required | ### Payload parameters | Parameter | Description | Required or optional | | ------------------- | ------------------- | -------------------- | | **userid** `string` | The new user's ID. | Required | | **iamid** `string` | The new user's IAM. | Required | ### Response ```json { "id": 6, "group": 2, "profile": 2, "createdAt": "2021-09-29T17:57:09.054Z", "updatedAt": "2021-09-29T17:57:09.054Z" } ``` | 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. | ## `PUT` `/bim/iam/{iamid}/group/{groupId}/authorizations/{attributeName}/{attributeValue}` Update the specified group's attributes. **Required Immuta permission**: `USER_ADMIN` ```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 ``` ### Request parameters | Parameter | Description | Required or optional | | --------------------------- | -------------------- | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **groupId** `integer` | The group ID. | Required | | **attributeName** `string` | The attribute name. | Required | | **attributeValue** `string` | The attribute value. | Required | ### Response Returns a [group object](#group-object-attributes). ## `GET` `/bim/group` Get the list of groups from all configured IAMs. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://demo.immuta.com/bim/group?size=25&sortOrder=asc ``` ### Query parameters
ParameterDescriptionRequired or optionalDefault valueAccepted values
name stringA partial name to match against group names.Optional--
ids string[]Filters results to return groups with specified IDs.Optional--
userid integerThe user ID. This will return the groups that the user is a member of.Optional--
iamid array[string]Optionally provide IAMs to filter the groups returned.Optional--
size integerThe maximum number of records to return.Optional25
offset integerOffset to start returning values.Optional--
sortField stringThe field to sort results on.Optionalname
  • name
  • createdAt
  • iamid
sortOrder stringThe order that the results will be sorted in.Optionalasc
  • asc
  • desc
nameOnly booleanIf true, results will only return distinct group names.Optional-
  • true
  • false
### Response Returns a list of [group objects](#group-object-attributes). ## `GET` `/bim/group/{groupId}` Get the specified group. **Required Immuta permission**: `USER_ADMIN` ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://demo.immuta.com/bim/group/2 ``` #### Query parameter | Parameter | Description | Required or optional | | --------------------- | -------------------- | -------------------- | | **groupId** `integer` | The ID of the group. | Required | ### Response Returns a [group object](#group-object-attributes). ## `GET` `/bim/group/{groupId}/user` Get group users. ```bash curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://demo.immuta.com/bim/group/2/user ``` ### Query parameters | Parameter | Description | Required or optional | Default value | Accepted values | | ---------------------- | --------------------------------------------- | -------------------- | ------------- | ------------------------------------------------------------ | | **groupId** `integer` | The ID of the group. | Required | - | - | | **offset** `integer` | Offset to start returning values. | Optional | - | - | | **size** `integer` | The maximum number of records to return. | Optional | `25` | - | | **sortOrder** `string` | The order that the results will be sorted in. | Optional | `asc` | | ### Response If the requesting user does not have the `USER_ADMIN` permission, only usernames (`profile.name`) will be returned in the response. Returns a list of [user objects](#user-object-attributes). ## `DELETE` `/bim/group/{groupId}` Delete the specified group. **Required Immuta permission**: `USER_ADMIN` ```bash curl \ --request DELETE \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ https://demo.immuta.com/bim/group/3 ``` ### Query parameter | Parameter | Description | Required or optional | | --------------------- | ------------- | -------------------- | | **groupId** `integer` | The group ID. | Required | ### Response If successful, returns `204`. ## `POST` `/bim/apikey` Create an API key for the currently authenticated user. **Requirement**: You must be a member of the project if creating an API key within a project ```bash curl -X 'POST' \ 'https://your.immuta.url.com/bim/apikey' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "projectId": 123, "name": "My CLI key" }' ``` ### Body parameters | Parameter | Description | Required or optional | Default values | Accepted values | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------- | ---------------- | | **projectId** `integer` | The project to assign this API key to. If omitted or set to `null`, the request will use the user's current project and set the API key context to `CURRENT_PROJECT`. | Optional | `null` | - | | **name** `string` | The name to associate with this API key. | Optional | `null` | Max length `254` | *The payload **must** have one or both of the two attributes above.* ### Response ```json { "apikey": "your-new-api-key", "keyid": 456, "project": 123, "name": "My CLI key", "context": "CURRENT_PROJECT" } ``` #### Error responses * **400**: User is not a member of the project specified; acknowledgement required; or other invalid request state. * **404**: Project not found. ## `POST` `/bim/iam/{iamId}/agent/{agentId}/tokens` Create a personal access token for an agent. The agent will use this token to make requests to the Immuta API to vend and manage ephemeral roles. **Requirement**: `USER_ADMIN` Immuta permission or own the agent {% code overflow="wrap" %} ```bash curl -X 'POST' \ 'https://www.organization.immuta.com/bim/iam/{iamId}/agent/{agentId}/tokens' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "description": "Marketing department agent token", "expirationDate": "2027-03-23" }' ``` {% endcode %} ### Path parameters | Parameter | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **iamId** `string` | The unique identifier of your identity provider. If you created the agent in Immuta, this value is `bim`. | | **agentId** `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 you can get it from the **Agents** page in the Immuta UI. | ### Body parameters | Parameter | Description | Required or optional | Default | | ------------------------- | --------------------------------------------------- | -------------------- | ------- | | **description** `string` | A description of the agent's personal access token. | Required | - | | **expirationDate** `date` | The date the token expires. | Optional | - | ### Response ```json { "token": "4d69ba7c8e8a4207bac96dd8ba06a7eb", "tokenId": "d42a0391-1ce9-499a-b75a-ab386c791a5f", "userType": "agent", "description": "Marketing department agent token", "active": true } ``` | Attribute | Description | | ------------------------ | ----------------------------------------------------- | | **token** `string` | The agent's personal access token. | | **tokenId** `string` | A unique identifier for the personal access token. | | **userType** `string` | The type of user, which will be `agent`. | | **description** `string` | The description of the agent's personal access token. | | **active** `boolean` | When `true`, the personal access token is active. | ## `GET` `/bim/iam/{iamId}/agent/{agentId}/tokens` List all personal access tokens for an agent. **Requirement**: `USER_ADMIN` Immuta permission or own the agent {% code overflow="wrap" %} ```bash curl -X 'GET' \ 'https://organization.immuta.com/bim/iam/bim/agent/158/tokens' \ -H 'accept: application/json' \ -H 'Authorization: Bearer 37544ec3aa7147ebb72077bd88e39cfa' ``` {% endcode %} ### Path parameters | Parameter | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **iamId** `string` | The unique identifier of your identity provider. If you created the agent in Immuta, this value is `bim`. | | **agentId** `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 you can get it from the **Agents** page in the Immuta UI. | ### Response ```json { "tokenId": "d42a0391-1ce9-499a-b75a-ab386c791a5f", "userType": "agent", "description": "Marketing department agent token", "active": true, "createdAt": "2026-09-09T13:16:29.272Z" } ``` | Attribute | Description | | ------------------------ | ----------------------------------------------------- | | **tokenId** `string` | A unique identifier for the personal access token. | | **userType** `string` | The type of user, which will be `agent`. | | **description** `string` | The description of the agent's personal access token. | | **active** `boolean` | When `true`, the personal access token is active. | | **createdAt** `date` | The date the personal access token was created. | | **expiresAt** `date` | The date the personal access token will expire. | ## `DELETE` `/bim/iam/{iamId}/agent/{agentId}/tokens/{tokenId}` Delete a personal access token for an agent. **Requirement**: `USER_ADMIN` Immuta permission or own the agent {% code overflow="wrap" %} ```bash curl -X 'DELETE' \ 'https://organization.immuta.com/bim/iam/bim/agent/158/tokens/d42a0291-1ce9-439a-b75a' \ -H 'accept: application/json' \ -H 'Authorization: Bearer 37544ec3aa7147ebb72077bd88e39cfa' ``` {% endcode %} ### Path parameters | Parameter | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **iamId** `string` | The unique identifier of your identity provider. If you created the agent in Immuta, this value is `bim`. | | **agentId** `string` | The unique identifier of the agent. You can get this ID [through the Immuta API](#get-bim-user) and using the agent's name as a search filter, or you can get it from the **Agents** page in the Immuta UI. | | **tokenId** `string` | The unique identifier of the personal access token. You can get this ID using the [list personal access tokens for an agent endpoint](#get-bim-iam-iamid-agent-agentid-tokens). | ### Response ```json { "deleted": true } ``` | Attribute | Description | | --------------------- | -------------------------------------------------------- | | **deleted** `boolean` | When `true`, the personal access token has been deleted. | ## `POST` `/bim/apikey/system` Create or return a system API key for a Trino connection. **Required Immuta permission**: `APPLICATION_ADMIN` {% hint style="info" %} **Idempotent behavior** If a system API key with the given `name` already exists and it matches the same `connectionKey` and `scopes`, the endpoint will return the existing key. To rotate the key, set `regenerate` to `true`. {% endhint %} ```bash curl -X 'POST' \ 'https://your.immuta.url.com/bim/apikey/system' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "name": "trino-connection-1", "scopes": ["plugin:trino"], "connectionKey": "connection-abc123", "regenerate": false }' ``` ### Body parameters | Parameter | Description | Required or optional | Default values | Accepted values | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | -------------- | ------------------ | | **name** `string` | The unique name to associate with the system API key. | Required | - | - | | **scopes** `array` | The scope of the API key. Must be non-empty and valid. Currently, the only supported scope is `["plugin:trino"]` | Required | - | `["plugin:trino"]` | | **connectionKey** `string` | The connection key for the connection the API key will be used with. | Required | - | - | | **regenerate** `boolean` |

If true, a new API key will be created even if there is already an API key associated with the same connection and scope.

If false, it will return the existing key.

| Optional | `false` | `true` or `false` | ### Response ```json { "apikey": "your-api-key", "keyid": 987, "name": "trino-connection-1" } ``` #### Error responses * **400**: Connection key not found, scopes invalid, or a key with the same name exists for a different connection or scope. ## `DELETE` `/bim/apikey/{keyid}` This also deletes all authentication tokens derived from that API key. **Requirement**: You must own the API key ```bash curl -X 'DELETE' \ 'https://your.immuta.url.com/bim/apikey/456' \ -H 'accept: application/json' \ -H 'Authorization: Bearer ' ``` ### Path parameter | Parameter | Description | | ------------------- | ----------- | | **keyid** `integer` | API key ID. | ### Response ```json { "revokedTokens": 12 } ``` #### Error responses * **403**: You may not delete another user's API key. * **404**: API key not found or no keys deleted. ## `DELETE` `/bim/apikey/system/{keyid}` Delete a system API key. **Required Immuta permission**: `APPLICATION_ADMIN` ```bash curl -X 'DELETE' \ 'https://your.immuta.url.com/bim/apikey/system/987' \ -H 'accept: application/json' \ -H 'Authorization: Bearer ' ``` ### Path parameter | Parameter | Description | | ------------------- | ------------------ | | **keyid** `integer` | System API key ID. | ### Response ```json { "revokedKeys": 1 } ``` #### Error responses * **404**: System API key not found. ## `POST` `/bim/apikey/authenticate` Authenticate with the Immuta API using an API key. ```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** ```json { "apikey": "100874dyour-api-key-79aa38bbfe0e8c787" } ``` ### Payload parameter | Parameter | Description | | ------------------- | ------------ | | **apikey** `string` | The API key. | ### Response ```json { "authenticated": true, "token": "be420************2745ea0307" } ``` | Attribute | Description | | --------------------------- | -------------------------------------------------------- | | **authenticated** `boolean` | If `true`, the user has been successfully authenticated. | | **token** `string` | The user's access token. | ## `POST` `/bim/apikey/impersonate` Impersonate another user using an API key. **Required Immuta permission**: `IMPERSONATE_USER` ```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** ```json { "apikey": "requesting-users-api-key", "userid": "user1@example.com", "iamid": "bim" } ``` ### Payload parameters | Parameter | 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 ```json { "authenticated": true, "token": "0753*************c61d2" } ``` | Attribute | Description | | --------------------------- | -------------------------------------------------------- | | **authenticated** `boolean` | If `true`, the user has been successfully authenticated. | | **token** `string` | The user's access token. | ## `POST` `/bim/token` Get information for a given token, should it exist. ```bash curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer dea464c07bd07300095caa8" \ --data @example-payload.json \ https://demo.immuta.com/bim/token ``` **Payload** ```json { "token": "48983da*********85220837d" } ``` ### Payload parameter | Parameter | Description | | ------------------ | ----------------- | | **token** `string` | The access token. | ### Response ```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 } ``` | 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. | ## `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. ```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 ``` ### Request parameters | Parameter | Description | Required or optional | | ------------------- | -------------------- | -------------------- | | **iamid** `string` | The IAM ID. | Required | | **userid** `string` | The user's username. | Required | ### Response ```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 } ] ``` | 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. | ## User object attributes | 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. | ## Detailed user object | 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** `array[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. | ## Group object attributes | Attribute | Description | | --------------------------- | -------------------------------------- | | **id** `integer` | The group ID. | | **iamid** `string` | The IAM ID. | | **name** `string` | The group name. | | **gid** `string` | The group's external ID (may be null). | | **email** `string` | The group email. | | **authorizations** `object` | Details on the group's attributes. | | **description** `string` | The group description. | | **scim** `boolean` | If `true`, the group is SCIM-managed. | | **scimid** `string` | The SCIM ID for the group. | | **createdAt** `timestamp` | The date the group was created. | | **updatedAt** `timestamp` | The date the group was last updated. | ## User profile attributes | 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`. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.