Skip to content

You are viewing documentation for Immuta version 2023.1.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

BIM API Reference Guide

This page details the bim API, which allows users to programmatically access information about users, their group memberships, and authentications. Most of the actions described here require ADMIN permissions.

Note

Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.

BIM workflow

Because the BIM endpoint encompasses groups, users, and authentications, there are three workflows.

Users workflow

  1. Create a new user.
  2. Manage your users.
  3. Review your users' information.
  4. Delete a user.

Groups workflow

  1. Create a new group.
  2. Manage groups.
  3. Search groups.
  4. Delete a group.

Authenticate with the API workflow

  1. Create an API Key.
  2. Authenticate with an API key.
  3. View tokens and API key information.
  4. Remove an API key.

Create a new user

Endpoint

Method Path Purpose
POST /bim/iam/bim/user Create a new BIM user.

Request Parameters

None.

Payload Parameters

Attribute Description Required
iamid string The IAM ID. Yes
userid string The new user's username. Yes
password string The new user's password. No
profile array Information on the new user's name and email. No
permissions array Information on the new user's permissions. No

Response Parameters

Attribute Description
id integer The user ID.
iamid string The IAM ID.
userid string The user's username.
bimAuthorizations array The attributes and groups given to the user's BIM profile.
iamAuthorizations array The attributes and groups given to the user's external IAM profile.
authorizations array The user's groups and attributes.
permissions array The user's permissions.
profile array Details on the user, including name, email, phone, about, location, organization, position, preferences, externalUserIds, scim, systemGenerated, id, createdAt, and updatedAt values.
lastLogin timestamp The date the user most recently logged into Immuta.
disabled boolean If true, the user is disabled.
createdAt timestamp The date the user was created.
updatedAt timestamp The date the user was last updated.
newUserLink string A link for the new user to log in and create a password.
emailFailed boolean If true, the login email was unable to be sent to the user's provided email address.
emailSent boolean If true, a login email was sent to the new user.

Request example

This example request with the payload below will create a new BIM user with the username charlie.doe@immuta.com.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/bim/iam/bim/user

Payload example

{
  "iamid": "bim",
  "userid": "charlie.doe@immuta.com",
  "profile": {
    "name": "Charlie Doe",
    "email": "charlie.doe@immuta.com"
  },
  "permissions": []
}

Response example

{
  "newUser": {
    "id": 18,
    "iamid": "bim",
    "userid": "charlie.doe@immuta.com",
    "bimAuthorizations": null,
    "iamAuthorizations": null,
    "authorizations": {},
    "permissions": ["CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT"],
    "profile": {
      "name": "Charlie Doe",
      "email": "charlie.doe@immuta.com",
      "phone": null,
      "about": null,
      "location": null,
      "organization": null,
      "position": null,
      "preferences": null,
      "externalUserIds": {},
      "scim": null,
      "systemGenerated": false,
      "id": 18,
      "createdAt": "2021-10-07T01:35:13.382Z",
      "updatedAt": "2021-10-07T01:35:13.382Z"
    },
    "authentication": null,
    "systemGenerated": false,
    "lastLogin": null,
    "lastExternalRefresh": "2021-10-07T01:35:13.000Z",
    "disabled": false,
    "createdAt": "2021-10-07T01:35:13.389Z",
    "updatedAt": "2021-10-07T01:35:13.389Z"
  },
  "newUserLink": "https://demo.immuta.com/login?token=******&userid=charlie.doe%40immuta.com&name=Charlie%20Doe",
  "emailFailed": false,
  "emailSent": false
}

Manage users

Method Path Purpose
GET /bim/iam/{iamid}/user/authenticate Authenticate a user from a 3rd party identity provider.
POST /bim/iam/{iamid}/user/authenticate Authenticate a user using their username and password and proxying it to the specified IAM service.
PUT /bim/iam/{iamid}/user/{userid}/profile Update a specified user's profile.
DELETE /bim/iam/{iamid}/user/{userid}/permissions/{permission} Remove the specified user's permission.
PUT /bim/iam/{iamid}/user/{userid}/permissions Update the specified user's permissions.
PUT /bim/iam/{iamid}/user/{userid}/password Update the specified user's password.
PUT /bim/iam/{iamid}/user/{userid}/disable/{disable} Disable / enable the specified BIM user.
POST /bim/syncUsers Sync Users for external IAM.
POST /iam/{iamId}/sync Sync LDAP users with Immuta.
PUT /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue} Update the specified user's attributes.
DELETE /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value} Remove an attribute from the specified group or user.
POST /bim/iam/bim/user/{userid}/clone Clones the provided user to create multiple additional user accounts.

Authenticate a user from an outside IAM

Endpoint

Method Path Purpose
GET /bim/iam/{iamid}/user/authenticate Authenticate a user from a 3rd-party identity provider.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes

Response Parameters

None.

Request example

This example request

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/LDAPIAM/user/authenticate

Authenticate user with username and password

Endpoint

Method Path Purpose
POST /bim/iam/{iamid}/user/authenticate Authenticate a user using their username and password and proxying it to the specified IAM service.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes

Payload Parameters

Attribute Description Required
username string The user's username for the IAM dictated in the request. Yes
password string The user's password for the IAM dictated in the request. Yes

Response Parameters

Attribute Description
authenticated boolean If true, the user has been successfully authenticated.
token string The user's access token.
tokenExperation timestamp The date the token will expire.
profileId integer The user ID.

Request example

This example request with the payload below will authenticate the user using the bim IAM.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/bim/iam/bim/user/authenticate
Payload example
{
  "username": "demo.user@immuta.com",
  "password": "********"
}

Response example

{
  "authenticated": true,
  "token": "6913229***********0d3da",
  "tokenExpiration": "2021-09-29T19:12:51.467Z"
}

Update a user profile

Endpoint

Method Path Purpose
PUT /bim/iam/{iamid}/user/{userid}/profile Update a specified user's profile.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
userId string The user's username. Yes

Payload Parameters

Attribute Description Required
iamid string The IAM ID. No
userid string The user's username. No
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, redshiftUser, and teradataUser. No
preferences array No
scim array No

Response Parameters

Attribute Description
profile array Details information about the user, including name, email, phone, about, location, organization, position, preferences, externalUserIds, scim, id, and the date of creation.
permissions array A list of the user's permissions.
iamid string The IAM ID.
userid string The user's username.
authorizations array The user's attributes and groups.
updatedAt timestamp The date the user was last updated.
disabled boolean If true, the user is disabled.
lastLogin timestamp The date the user last logged in.
bimAuthorizations array The attributes and groups given to the user's BIM profile.
iamAuthorizations array The attributes and groups given to the user's external IAM profile.
hasLogin boolean If true, the user has logged into Immuta.

Request example

This example request will change the location to Boston, MA for the user with the username jane.doe@immuta.com.

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe@immuta.com/profile
Payload example
{
  "email": "jane.doe@immuta.com",
  "phone": null,
  "about": null,
  "location": "Boston, MA",
  "organization": null,
  "position": "",
  "preferences": {
    "sortDataSourceState": {
      "column": "name",
      "order": "asc",
      "size": 12
    },
    "sortProjectDataSourceState": {
      "column": "dataSourceName",
      "order": "asc",
      "size": 12
    },
    "sortProjectState": {
      "column": "name",
      "order": "asc",
      "size": 12
    },
    "notifications": {
      "email": false
    },
    "tabDataSourceState": 0,
    "tabProjectState": 0,
    "dataSourceOverrides": {},
    "showPolicySearchDetailLabels": true
  },
  "externalUserIds": {},
  "scim": null,
  "systemGenerated": false,
  "iamid": "bim",
  "userid": "jane.doe@immuta.com"
}

Response example

{
  "name": "Jane Doe",
  "email": "jane.doe@immuta.com",
  "phone": null,
  "about": null,
  "location": "Boston, MA",
  "organization": null,
  "position": null,
  "externalUserIds": {},
  "systemGenerated": false,
  "id": 2,
  "createdAt": "2021-08-16T20:30:43.698Z",
  "updatedAt": "2021-10-18T20:49:06.237Z",
  "preferences": {
    "sortProjectState": {
      "column": "name",
      "order": "asc",
      "size": 12
    },
    "currentProject": null,
    "sortDataSourceState": {
      "column": "name",
      "order": "asc",
      "size": 12
    },
    "sortProjectDataSourceState": {
      "column": "dataSourceName",
      "order": "asc",
      "size": 12
    },
    "notifications": {
      "email": false
    },
    "tabDataSourceState": 0,
    "tabProjectState": 0,
    "dataSourceOverrides": {},
    "showPolicySearchDetailLabels": true
  },
  "scim": null
}

Remove a user's permissions

Endpoint

Method Path Purpose
DELETE /bim/iam/{iamid}/user/{userid}/permissions/{permission} Remove the specified user's permission.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
userid string The user's username. Yes
permission string The permission to remove. See Immuta permissions and personas for a list of Immuta permissions. Yes

Response Parameters

Attribute Description
id integer The user's ID.
iamid string The IAM ID.
userid string The user's username.
bimAuthorizations array The attributes and groups given to the user's BIM profile.
iamAuthorizations array The attributes and groups given to the user's external IAM profile.
authorizations array Details on the user's groups and attributes.
permissions array[string] A list of the user's permissions.
profile integer The user's profile ID.
lastLogin timestamp The date the user last logged into Immuta.
disabled boolean If true, the user is disabled.
createdAt timestamp The date the user was created.
updatedAt timestamp The date the user was last updated.

Request example

This example request will delete the permission CREATE_DATA_SOURCE_IN_PROJECT from the user with the username john.doe@immuta.com.

curl \
  --request DELETE \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/john.doe%40immuta.com/permissions/CREATE_DATA_SOURCE_IN_PROJECT

Response example

{
  "id": 3,
  "iamid": "bim",
  "userid": "john.doe@immuta.com",
  "bimAuthorizations": null,
  "iamAuthorizations": null,
  "authorizations": {},
  "permissions": [
    "CREATE_PROJECT",
    "CREATE_DATA_SOURCE"
  ],
  "profile": 3,
  "authentication": 3,
  "systemGenerated": false,
  "lastLogin": "2021-09-27T15:29:00.154Z",
  "lastExternalRefresh": "2021-09-27T15:29:00.154Z",
  "disabled": false,
  "createdAt": "2021-08-19T19:33:38.582Z",
  "updatedAt": "2021-10-06T22:03:48.611Z"
}

Update a user's permissions

Endpoint

Method Path Purpose
PUT /bim/iam/{iamid}/user/{userid}/permissions Update the specified user's permission.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
userid string The user's username. Yes

Request Parameters

Attribute Description Required
permissions array[string] A list of the user's permissions. This list is going to be a comprehensive list of all of the user's permissions. See Immuta permissions and personas for a list of Immuta permissions. Yes

Response Parameters

Attribute Description
id integer The user's ID.
iamid string The IAM ID.
userid string The user's username.
bimAuthorizations array The attributes and groups given to the user's BIM profile.
iamAuthorizations array The attributes and groups given to the user's external IAM profile.
authorizations array Details on the user's groups and attributes.
permissions array A list of the user's permissions.
profile integer The user's profile ID.
lastLogin timestamp The date the user last logged into Immuta.
disabled boolean If true, the user is disabled.
createdAt timestamp The date the user was created.
updatedAt timestamp The date the user was last updated.

Request example

This example request with the payload below will change to permissions of the user with the username charlie.doe@immuta.com to CREATE_DATA_SOURCE_IN_PROJECT, CREATE_PROJECT, and CREATE_DATA_SOURCE.

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/charlie.doe%40immuta.com/permissions
Payload example
[
  "CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT", "CREATE_DATA_SOURCE"
]

Response example

{
  "id": 18,
  "iamid": "bim",
  "userid": "charlie.doe@immuta.com",
  "bimAuthorizations": null,
  "iamAuthorizations": null,
  "authorizations": {},
  "permissions": [
    "CREATE_DATA_SOURCE_IN_PROJECT",
    "CREATE_PROJECT",
    "CREATE_DATA_SOURCE"
  ],
  "profile": 18,
  "authentication": null,
  "systemGenerated": false,
  "lastLogin": null,
  "lastExternalRefresh": "2021-10-07T01:35:13.000Z",
  "disabled": false,
  "createdAt": "2021-10-07T01:35:13.389Z",
  "updatedAt": "2021-10-07T16:10:40.214Z"
}

Update a user's password

Endpoint

Method Path Purpose
PUT /bim/iam/{iamid}/user/{userid}/password Update the specified user's password.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
userid string The user's username. Yes

Request Parameters

Attribute Description Required
originalPassword string The user's old password. Yes
password string The user's new password. Yes

Response Parameters

Attribute Description
success boolean If true, the user's password has been successfully changed to the new password.

Request example

This example request with the payload below will change the password of the user with the ID jane.doe@immuta.com.

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe%40immuta.com/password
Payload example
{
  "originalPassword": "old********",
  "password": "new********"
}

Response example

{
  "success": true
}

Disable or enable a user

Endpoint

Method Path Purpose
PUT /bim/iam/{iamid}/user/{userid}/disable/{disable} Disable / enable the specified BIM user.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
userid string The user's username. Yes
disable boolean If true, the user will be disabled. Yes

Response Parameters

Attribute Description
userid string The user's username.
disabled boolean If true, the user is disabled.

Request example

This example request will disabled the user with the username jane.doe@immuta.com.

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe%40immuta.com/disable/true

Response example

{
  "userid": "jane.doe@immuta.com",
  "disabled": true
}

Sync users from an external IAM

Endpoint

Method Path Purpose
POST /bim/syncUsers Sync users from an external IAM.

Request Parameters

None.

Payload Parameters

Attribute Description Required
iamid string The external IAM ID. Yes

Response Parameters

None.

Request example

This example request will sync the users from the specified external IAM with Immuta.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/bim/syncUsers
Payload example
{
  "iamid": "ldap"
}

Sync LDAP users with Immuta

Endpoint

Method Path Purpose
POST /iam/{iamId}/sync Sync LDAP users with Immuta.

Request Parameters

Attribute Description Required
iamId string The external IAM ID. Yes

Payload Parameters

Attribute Description Required
dryRun boolean If true, no updates will actually be made. Yes
iamConfig array Details about the IAM configuration, including authenticationOnly, credentials, defaultPermissions, displayName, id, ldapSync, and options. No
plugin string The type of plugin the IAM uses, ldap. No
schema array Details about the IAM schema, including group, profile, authorizations, and externalUserIds. No
supportedActions string No
type string The type of IAM, ldap. No

Response Parameters

Attribute Description
totalCount integer The total number of users in the external IAM that could be synced over into Immuta.
importedUsers array Details about the users who were successfully imported from the sync, including userId and dn.
refreshedUsers array Details about the users who were successfully refreshed from the sync, including userId and dn.
disabledUsers array Details about the users who were successfully disabled from the sync, including userId and dn.
enabledUsers array Details about the users who were successfully enabled from the sync, including userId and dn.
runningInBackground boolean If true, the sync created a job to run in the background.
count integer The number of users successfully updated from the IAM.

Request example

This example request will sync the users from Jump Cloud with Immuta.

curl -X 'POST' \
  'https://demo.immuta.com/iam/JumpCloud/sync' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 496ac257b8db4a96a16715fb4ed048dc' \
Payload example
{
  "dryRun": true,
  "iamConfig": {
    "authenticationOnly": false,
    "credentials": {
      "bind_dn": "uid=bind-user,ou=Users,o=redacted,dc=jumpcloud,dc=com"
    },
    "defaultPermissions": ["CREATE_DATA_SOURCE", "CREATE_PROJECT"],
    "displayName": "Jump Cloud LDAP",
    "id": "jumpcloudLDAPIAM",
    "ldapSync": {},
    "options": {
      "groupSearchFilter": "(&(objectClass=groupOfNames)(cn=%s*))",
      "host": "ldap.jumpcloud.com",
      "port": 636,
      "useSSL": true,
      "userGroupSearchFilter": "(member=<dn>)",
      "userSearchBase": "o=redacted,dc=jumpcloud,dc=com",
      "userSearchFilter": "mail=%s",
      "allowIdPInitiatedSSO": false
    },
    "plugin": "ldap",
    "schema": {
      "group": {
        "name": "cn"
      },
      "profile": {
        "email": "mail",
        "name": "cn",
        "phone": "phone"
      },
      "authorizations": {},
      "externalUserIds": {}
    },
    "supportedActions": ["syncGroups"],
    "type": "ldap"
  }
}

Response example

{
  "totalCount": 10,
  "importedUsers": [{
    "userId": "user-1@example.com",
    "dn": "uid=user-1,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "user-2@example.com",
    "dn": "uid=user-2,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "user-3@example.com",
    "dn": "uid=user-3,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "user-4@example.com",
    "dn": "uid=user-4,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }, {
    "userId": "user-5@example.com",
    "dn": "uid=user-5,ou=Users,o=redacted,dc=jumpcloud,dc=com"
  }],
  "refreshedUsers": [],
  "disabledUsers": [],
  "enabledUsers": [],
  "count": 5
}

Update a user's or group's attributes

Endpoint

Method Path Purpose
PUT /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{attributeName}/{attributeValue} Update the specified user's attributes.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
modelType string The type of model the attribute is added to. Options include group or user. Yes
modelID string The user or group ID. Yes
attributeName string The attribute name. Yes
attributeValue string The attribute value. Yes

Response Parameters

Attribute Description
id integer The user or group ID.
iamid string The IAM ID.
userid string The user's username.
name string The group name.
bimAuthorizations array The attributes and groups given to the user's BIM profile.
iamAuthorizations array The attributes and groups given to the user's external IAM profile.
authorizations array Details on the user's or group's and attributes.
permissions array A list of the user's permissions.
profile integer The user's profile ID.
lastLogin timestamp The date the user last logged into Immuta.
disabled boolean If true, the user is disabled.
createdAt timestamp The date the user was created.
updatedAt timestamp The date the user was last updated.

Request example

This example request will add the attribute Finance.Red Team to the user with the username jane.doe@immuta.com.

curl \
  --request PUT \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe@immuta.com/authorizations/Finance/Red%20Team

Response example

{
  "id": 16,
  "iamid": "bim",
  "userid": "jane.doe@immuta.com",
  "bimAuthorizations": {
    "Finance": ["CFA", "Red Team"]
  },
  "iamAuthorizations": null,
  "authorizations": {
    "Finance": ["CFA", "Red Team"]
  },
  "permissions": ["CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT"],
  "profile": 16,
  "authentication": 5,
  "systemGenerated": false,
  "lastLogin": "2021-10-07T02:58:31.708Z",
  "lastExternalRefresh": "2021-10-07T02:58:31.708Z",
  "disabled": false,
  "createdAt": "2021-10-06T22:17:46.500Z",
  "updatedAt": "2021-10-18T17:09:53.711Z"
}

Remove a user or group's attribute

Endpoint

Method Path Purpose
DELETE /bim/iam/{iamid}/{modelType}/{modelId}/authorizations/{key}/{value} Remove an attribute from the specified group or user.

Request Parameters

Attribute Description Required
iamid string The ID for the IAM the user or group is under. Yes
modelId string The user or group ID. Yes
modelType string The type of model the attribute is being removed from. Options include group or user. Yes
key string The attribute to remove. Yes
value string The attribute value to remove. No

Response Parameters

Attribute Description
id integer The user or group ID.
iamid string The IAM ID.
authorizations array The user or group attributes after the request has been made.
permissions array The user or group permissions.
profile integer The profile ID, if the model is a user.
systemGenerated boolean If true, the user was created by Immuta.
createdAt timestamp The date the user or group was created.
updatedAt timestamp The date the user or group was last updated.

Request example

This example request will remove the attribute Country.JP from the user with the user ID jane.doe@immuta.com.

curl \
  --request DELETE \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe@demo.com/authorizations/Country/JP

Response example

{
  "id": 4,
  "iamid": "bim",
  "userid": "jane.doe@demo.com",
  "bimAuthorizations": {
    "Country": ["US"],
    "Environment": ["Dev"],
    "OfficeLocation": ["Japan"]
  },
  "iamAuthorizations": null,
  "authorizations": {
    "Country": ["US"],
    "Environment": ["Dev"],
    "OfficeLocation": ["Japan"]
  },
  "permissions": ["CREATE_DATA_SOURCE_IN_PROJECT", "CREATE_PROJECT", "USER_ADMIN", "GOVERNANCE"],
  "profile": 4,
  "authentication": 3,
  "systemGenerated": false,
  "lastLogin": "2022-08-11T01:36:01.947Z",
  "lastExternalRefresh": "2022-08-11T01:36:01.947Z",
  "disabled": false,
  "createdAt": "2022-06-02T17:37:24.515Z",
  "updatedAt": "2022-08-11T18:40:51.366Z"
}

Clone user

Configure SMTP

SMTP must be configured to use this endpoint. Additionally, after the users are created, they will not be active until they sign in to the Immuta UI.

Endpoint

Method Path Purpose
POST /bim/iam/bim/user/{userid}/clone Clones the provided user (including their permissions, groups, and attributes) to create multiple additional user accounts.

Request Parameters

Attribute Description Required
userId string The user's username. Yes

Payload Parameters

Attribute Description Required
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.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/jane.doe%40demo.com/clone

Payload example

[
  "john.doe@demo.com"
]

Response example

{
  "failedEmails": []
}

Review user information

Method Path Purpose
GET /bim/iam Get a listing of configured IAM services.
GET /bim/user Administrative search over the aggregated view of all users.
GET /bim/rpc/user/current Get the currently logged in user's information.
GET /bim/iam/{iamid}/user/{id} Get the specified user's aggregated view.
GET /bim/iam/{iamid}/user/{userid}/profile Get the specified user's profile.
GET /bim/iam/{iamid}/user/{userid}/groups Get the specified user's list of groups.

Search all IAMs

Endpoint

Method Path Purpose
GET /bim/iam Get a listing of configured IAM services.

Query Parameters

None.

Response Parameters

Attribute Description
id string The IAM ID.
displayName string The name displayed in Immuta and entered at the time of configuration.
type string The identity provider type.
oauth boolean When true, the IAM service uses OAuth framework for authorization.

Request example

The request below will list all of the IAMs in use.

curl \
    --request GET \
      --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/iam

Response example

[
  {
    "id": "bim",
    "displayName": "Immuta",
    "type": "built-in",
    "oauth": false
  },
  {
    "id": "oktaSamlIAM",
    "displayName": "Okta SAML",
    "type": "saml",
    "oauth": false
  },
  {
    "id": "ldap",
    "displayName": "LDAP",
    "type": "ldap"
  }
]

Search all users

Endpoint

Method Path Purpose
GET /bim/user Administrative search over the aggregated view of all users.

Query Parameters

Attribute Description Required
size integer The maximum number of records to return. The default is 25. No
name string A partial name to match against user names. No
userid string A partial ID to match against user IDs. No
email string A partial email address to match against user email addresses. No
iamid [array]string Optionally provide the IAM to filter the users. No
excludeSystemGenerated boolean If true, the results will exclude accounts automatically created for handlers that periodically crawl and ingest. No
excludeAdminAndGovernor boolean If true, Admin and Governor accounts will be excluded. No
excludeDeletediams boolean If true, the results will exclude users for any IAMs that are no longer configured. No
excludebim boolean If true, users from the Immuta internal identity manager will be excluded. No
includeDisabled boolean If true, the results will include disabled users. No
offset integer Offset to start returning values. No
sortField string The field to sort results on. The default is user name. Possible values: name, createdAt, iamid, email. No
sortOrder string The order that the results will be sorted in. The default is asc. Possible values: asc, desc. No
permission string A permission to filter the users by. No

Response Parameters

Attribute Description
count integer Total number of results. May be greater than the length of hits if additional results exist. Use size and offset to page additional results.
hits metadata Details for each result, including id, iamid, userid, bimAuthorizations, iamAuthorizations, authorizations, projectId, permissions, groupPermissions, profile, authentication, systemGenerated, lastLogin, lastExternalRefresh, disabled, hasLogin, groups, createdAt, updatedAt, and schema values.
id integer The user ID.
iamid string The ID of the IAM the user is connected to.
userid string The user's username.
bimAuthorizations array The attributes and groups given to the user's BIM profile.
iamAuthorizations array The attributes and groups given to the user's external IAM profile.
authorizations metadata Details on the user's attributes.
projectId integer The project ID for the user's current project.
permissions string A list of the user's permissions.
profile metadata Details on the user, including name, email, phone, about, location, organization, position, preferences, externalUserIds, scim, systemGenerated, id, createdAt, and updatedAt values.
lastLogin timestamp The date of the user's last Immuta login.
disabled boolean If true, the user has been disabled.
hasLogin boolean If true, the user has logged into Immuta.
groups metadata Information on the user's groups.
createdAt timestamp The date the user was created.
updatedAt timestamp The date of the last time the user's information was updated.

Request example

The request below will search all of the users in Immuta.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/user?size=25&name=bar&sortOrder=asc

Response example

{
  "count": "2",
  "hits": [
    {
      "id": 18,
      "iamid": "bim",
      "userid": "bspringer@immuta.com",
      "permissions": [
        "CREATE_DATA_SOURCE",
        "CREATE_PROJECT"
      ],
      "profile": {
        "name": "Barrett Springer",
        "email": "bspringer@immuta.com",
        "id": 18,
        "createdAt": "2018-07-05T07:37:06.569Z",
        "updatedAt": "2018-07-05T07:37:06.569Z"
      },
      "authentication": 18,
      "systemGenerated": false,
      "lastLogin": "2018-07-05T07:39:56.365Z",
      "disabled": false,
      "createdAt": "2018-07-05T07:37:05.987Z",
      "updatedAt": "2018-07-05T07:37:05.987Z"
    },
    {
      "id": 5,
      "iamid": "bim",
      "userid": "bhoward@immuta.com",
      "authorizations": {
        "auth": [
          "SOMETHING_ELSE"
        ]
      },
      "permissions": [
        "CREATE_DATA_SOURCE",
        "CREATE_PROJECT",
        "AUDIT"
      ],
      "profile": {
        "name": "Barry Howard",
        "email": "bhoward@immuta.com",
        "preferences": {
          "sortDataSourceState": {
            "column": "name",
            "order": "asc",
            "size": 12
          },
          "sortProjectState": {
            "column": "name",
            "order": "asc",
            "size": 12
          }
        },
        "id": 5,
        "createdAt": "2018-07-05T07:37:06.392Z",
        "updatedAt": "2018-07-05T22:32:43.864Z"
      },
      "authentication": 5,
      "systemGenerated": false,
      "lastLogin": "2018-07-05T22:32:44.167Z",
      "disabled": false,
      "createdAt": "2018-07-05T07:37:05.818Z",
      "updatedAt": "2018-07-05T07:37:05.818Z"
    }
  ]
}

View current user's information

Endpoint

Method Path Purpose
GET /bim/rpc/user/current Get the currently logged in user's information.

Query Parameters

None.

Response Parameters

Attribute Description
id integer The user ID.
iamid string The ID of the IAM the user is connected to.
userid string The user's username.
bimAuthorizations array The attributes and groups given to the user's BIM profile.
iamAuthorizations array The attributes and groups given to the user's external IAM profile.
authorizations metadata Details on the user's attributes.
projectId integer The project ID for the user's current project.
permissions string A list of the user's permissions.
profile metadata Details on the user, including name, email, phone, about, location, organization, position, preferences, externalUserIds, scim, systemGenerated, id, createdAt, and updatedAt values.
lastLogin timestamp The date of the user's last Immuta login.
disabled boolean If true, the user has been disabled.
hasLogin boolean If true, the user has logged into Immuta.
groups metadata Information on the user's groups.
createdAt timestamp The date the user was created.
updatedAt timestamp The date of the last time the user's information was updated.

Request example

This request will return information on the user that is logged in.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/rpc/user/current

Response example

{
  "profile": {
    "name": "Barrett Springer",
    "email": "bspringer@immuta.com",
    "phone": null,
    "about": null,
    "location": null,
    "organization": null,
    "position": null,
    "preferences": null,
    "hdfsUser": null,
    "id": 18,
    "createdAt": "2018-07-05T07:37:06.569Z",
    "updatedAt": "2018-07-05T07:37:06.569Z"
  },
  "permissions": [
    "CREATE_DATA_SOURCE",
    "CREATE_PROJECT"
  ],
  "authorizations": {
    "Roles": [
      "Analyst"
    ],
    "Location": [
      "Columbus"
    ]
  },
  "iamid": "bim",
  "userid": "bspringer@immuta.com",
  "authorizations": null,
  "updatedAt": "2018-07-05T07:37:05.987Z",
  "systemGenerated": false,
  "disabled": false,
  "hasLogin": true,
  "lastLogin": "2018-07-05T07:39:56.365Z"
}

View a user's information

Endpoint

Method Path Purpose
GET /bim/iam/{iamid}/user/{id} Gets the specified user's aggregated view.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
id integer The user ID. Yes
params query No

Response Parameters

Attribute Description
profile array Details about the user, including name, email, phone, about, location, organization, position, preferences, externalUserIds, scim, id, and the date of creation.
preferences array Information about the user's tabDataSourceState, tabProjectState, sortDataSourceState, and currentProject.
permissions array A list of the user's permissions.
iamid string The IAM ID.
userid string The user's username.
authorizations array The user's attributes and groups.
updatedAt timestamp The date the user was last updated.
systemGenerated boolean
disabled boolean If true, the user is disabled.
lastLogin timestamp The date the user last logged in.
lastExternalRefresh timestamp
bimAuthorizations array The attributes and groups given to the user's BIM profile.
iamAuthorizations array The attributes and groups given to the user's external IAM profile.
hasLogin boolean If true, the user has logged into Immuta.

Request example

This example request will return information about the user with the ID 2.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/2

Response example

{
  "profile": {
    "name": "John Doe",
    "email": "john.doe@immuta.com",
    "phone": null,
    "about": null,
    "location": null,
    "organization": null,
    "position": null,
    "preferences": {
      "sortProjectState": {
        "column": "name",
        "order": "asc",
        "size": 12
      },
      "currentProject": null
    },
    "externalUserIds": {},
    "scim": null,
    "systemGenerated": false,
    "id": 2,
    "createdAt": "2021-08-16T20:30:43.698Z",
    "updatedAt": "2021-09-14T01:17:02.786Z"
  },
  "permissions": [
    "CREATE_DATA_SOURCE_IN_PROJECT",
    "CREATE_PROJECT",
    "CREATE_DATA_SOURCE",
    "USER_ADMIN",
    "APPLICATION_ADMIN",
    "AUDIT",
    "GOVERNANCE",
    "IMPERSONATE_HDFS_USER",
    "CREATE_S3_DATASOURCE_WITH_INSTANCE_ROLE",
    "FETCH_POLICY_INFO",
    "CREATE_FILTER",
    "IMPERSONATE_USER",
    "PROJECT_MANAGEMENT"
  ],
  "iamid": "bim",
  "userid": "jane.doe@immuta.com",
  "authorizations": {},
  "updatedAt": "2021-09-29T17:57:09.059Z",
  "systemGenerated": false,
  "disabled": false,
  "lastLogin": "2021-09-30T19:20:03.327Z",
  "lastExternalRefresh": "2021-09-30T19:20:03.327Z",
  "bimAuthorizations": null,
  "iamAuthorizations": null,
  "hasLogin": true
}

View a user profile

Endpoint

Method Path Purpose
GET /bim/iam/{iamid}/user/{userid}/profile Gets the specified user's profile.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
id integer The user ID. Yes

Response Parameters

Attribute Description
name string The user's name.
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.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/2/profile

Response example

{
  "name": "John Doe",
  "email": "john.doe@immuta.com",
  "phone": null,
  "about": null,
  "location": null,
  "organization": null,
  "position": null,
  "preferences": {
    "sortProjectState": {
      "column": "name",
      "order": "asc",
      "size": 12
    },
    "currentProject": null
  },
  "externalUserIds": {},
  "scim": null,
  "systemGenerated": false,
  "id": 2,
  "createdAt": "2021-08-16T20:30:43.698Z",
  "updatedAt": "2021-09-14T01:17:02.786Z"
}

View a user's groups

Endpoint

Method Path Purpose
GET /bim/iam/{iamid}/user/{userid}/groups Get the specified user's list of groups.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
userid string The user's username. Yes

Response Parameters

Attribute Description
id integer The group ID.
name string The group name.
iamid string The IAM ID.
groupUser integer The user's ID within the group.

Request example

This example request will return information on the groups of the user with the username john.doe@immuta.com.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/john.doe%40immuta.com/groups

Response example

[
  {
    "id": 2,
    "name": "API Group #2",
    "iamid": "bim",
    "groupUser": 6
  }
]

Delete a user

Endpoint

Method Path Purpose
DELETE /bim/iam/bim/user/{userid} Delete the specified user in Immuta.

Request Parameters

Attribute Description Required
userid string The user's username. Yes

Response Parameters

Attribute Description
userid string The user's username.
iamid string The IAM ID.

Request example

This example request will delete the user with the username charlie.doe@immuta.com.

curl \
  --request DELETE \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/charlie.doe%40immuta.com

Response example

{
  "userid": "charlie.doe@immuta.com",
  "iamid": "bim"
}

Create a new group

Endpoint

Method Path Purpose
POST /bim/group Create a new group.

Query Parameters

None.

Payload Parameters

Attribute Description Required
iamid string The IAM ID. Yes
name string The new group name. Yes
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.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/bim/group

Payload example

{
  "iamid": "bim",
  "name": "API Group"
}

Response example

{
  "id": 3,
  "iamid": "bim",
  "name": "API Group",
  "gid": null,
  "email": null,
  "authorizations": null,
  "description": null,
  "scim": null,
  "scimid": null,
  "createdAt": "2021-09-29T15:15:26.615Z",
  "updatedAt": "2021-09-29T15:15:26.615Z"
}

Manage groups

Method Path Purpose
PUT /bim/group/{groupId} Update the specified group.
DELETE /bim/group/{groupId}/user/{groupuserid} Remove a user from a group.
POST /bim/group/{groupId}/user Add a new user to a group.
PUT /bim/iam/{iamid}/group/{groupid}/authorizations Update the specified group's authorizations.

Update a group

Endpoint

Method Path Purpose
PUT /bim/group/{groupId} Update the specified group.

Request Parameters

Attribute Description Required
groupId integer The group ID. Yes

Payload Parameters

Attribute Description Required
name string The group's new name. No
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.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/bim/group/2
Payload example
{
  "name": "API Group #2",
  "description": "This group was edited through the API"
}

Response example

{
  "id": 2,
  "iamid": "bim",
  "name": "API Group #2",
  "gid": null,
  "email": "blue.team@immuta.com",
  "authorizations": {
    "Finance": [
      "CFA"
    ]
  },
  "description": "This group was edited through the API",
  "scim": null,
  "scimid": null,
  "createdAt": "2021-09-16T17:24:55.066Z",
  "updatedAt": "2021-09-29T17:32:07.725Z"
}

Remove a user from a group

Endpoint

Method Path Purpose
DELETE bim/group/{groupId}/user/{groupuserid} Remove a user from a group.

Request Parameters

Attribute Description Required
groupId integer The group ID. Yes
groupuserid integer The user's group ID. Yes

Response Parameters

None.

Request example

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/group/1/user/2

Add a user to a group

Endpoint

Method Path Purpose
POST bim/group/{groupId}/user Add a new user to a group.

Request Parameters

Attribute Description Required
groupId integer The group ID. Yes

Payload Parameters

Attribute Description Required
userid string The new user's ID. Yes
iamid string The new user's IAM. Yes

Response Parameters

Attribute Description
id integer The user's group ID.
group integer The group ID.
profile integer The user ID.
createdAt timestamp The date the user was added to the group.
updatedAt timestamp The date the user was last updated within the group.

Request example

This request with the payload below adds the user with the ID tom.jones@immuta.com to the group with the ID 2.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --data @example-payload.json \
    https://demo.immuta.com/bim/group/2/user
Payload example
{
  "userid": "tom.jones@immuta.com",
  "iamid": "bim"
}

Response example

{
  "id": 6,
  "group": 2,
  "profile": 2,
  "createdAt": "2021-09-29T17:57:09.054Z",
  "updatedAt": "2021-09-29T17:57:09.054Z"
}

Update a group's attributes

Endpoint

Method Path Purpose
PUT /bim/iam/{iamid}/group/{groupid}/authorizations/{attributeName}/{attributeValue} Update the specified group's attributes.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
groupId integer The group ID. Yes
attributeName string The attribute name. Yes
attributeValue string The attribute value. Yes

Response Parameters

Attribute Description
id integer The group ID.
iamid string The IAM ID.
name string The group name.
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.

curl \
    --request PUT \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/iam/bim/group/2/authorizations/Finance/Red%20Team

Response example

{
  "id": 2,
  "iamid": "bim",
  "name": "API Group #2",
  "gid": null,
  "email": "blue.team@immuta.com",
  "authorizations": {
    "Finance": ["CFA", "Red Team"]
  },
  "description": "This group was edited through the API",
  "scim": null,
  "scimid": null,
  "createdAt": "2021-09-16T17:24:55.066Z",
  "updatedAt": "2021-10-08T13:41:06.211Z"
}

Search groups

Method Path Purpose
GET /bim/group Get the list of groups from all configured IAMs.
GET /bim/group/{groupId} Get the specified group.
GET /bim/group/{groupId}/user Get group users.

Search all groups from all IAMs

Endpoint

Method Path Purpose
GET /bim/group Get the list of groups from all configured IAMs.

Query Parameters

Attribute Description Required
name string A partial name to match against group names. No
userid integer The user ID. This will return the groups that the user is a member of. No
iamid string Optionally provide the IAM to filter the groups. No
size integer The maximum number of records to return. The default is 25. No
offset integer Offset to start returning values. No
sortField string The field to sort results on. Possible values: name, createdAt, iamid. Default is name. No
sortOrder string The order that the results will be sorted in. Possible values: asc, desc. The default is asc. No
nameOnly boolean If true, results will only return distinct group names. No

Response Parameters

Attribute Description
count integer Total number of results. May be greater than the length of hits if additional results exist. Use size and offset to page additional results.
hits metadata Details on each result, including id, iamid, name, gid, email, authorizations, description, scim, scimid, createdAt, and updatedAt values.
id integer The group ID.
iamid string The IAM ID.
name string The name of the group.
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.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/group?size=25&sortOrder=asc

Response example

{
  "count": "3",
  "hits": [
    {
      "id": 2,
      "iamid": "bim",
      "name": "engineers",
      "gid": null,
      "email": "engineers@immuta.com",
      "authorizations": null,
      "description": null,
      "createdAt": "2018-07-05T07:37:07.209Z",
      "updatedAt": "2018-07-05T07:37:07.209Z"
    },
    {
      "id": 1,
      "iamid": "bim",
      "name": "founders",
      "gid": null,
      "email": null,
      "authorizations": null,
      "description": null,
      "createdAt": "2018-07-05T07:37:07.177Z",
      "updatedAt": "2018-07-05T07:37:07.177Z"
    },
    {
      "id": 20,
      "iamid": "bim",
      "name": "system administrators",
      "gid": null,
      "email": null,
      "authorizations": null,
      "description": null,
      "createdAt": "2018-07-05T07:37:07.595Z",
      "updatedAt": "2018-07-05T07:37:07.595Z"
    }
  ]
}

Search a specific group

Endpoint

Method Path Purpose
GET /bim/group/{groupid} Get the specified group.

Query Parameters

Attribute Description Required
groupId integer The ID of the group. Yes

Response Parameters

Attribute Description
id integer The group's ID.
iamid string The IAM ID.
name string The group's name.
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.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/group/2

Response example

{
  "id": 2,
  "iamid": "bim",
  "name": "engineers",
  "gid": null,
  "email": "engineers@immuta.com",
  "authorizations": {
    "Location": [
      "College Park"
    ]
  },
  "description": null,
  "createdAt": "2018-07-05T07:37:07.209Z",
  "updatedAt": "2018-07-06T01:42:55.518Z"
}

Search a group's users

Endpoint

Method Path Purpose
GET /bim/group/{groupid}/user Get group users.

Query Parameters

Attribute Description Required
groupId integer The ID of the group. Yes
offset integer Offset to start returning values. No
size integer The maximum number of records to return. The default is 25. No
sortOrder string The order that the results will be sorted in. Possible values: asc, desc. The default is asc. No

Response Parameters

Attribute Description
count integer Total number of results. May be greater than the length of hits if additional results exist. Use size and offset to page additional results.
hits metadata Details for each result, including id, group, profile, uid, iamid, userid, disabled, scim, scimid, createdAt, and updatedAt values.
id integer The group ID.
iamid string The ID of the IAM the user is connected to.
userid string The user's username.
profile metadata Details on the user, including iamid, userid, name, email, phone, about, location, organization, position, preferences, externalUserIds, scim, systemGenerated, id, createdAt, and updatedAt values.
disabled boolean If true, the user has been disabled.
group integer The group ID.
createdAt timestamp The date the user was created.
updatedAt timestamp The date of the last time the user's information was updated.

Request example

This request will return information on the users in the group with the ID 2.

curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/group/2/user

Response example

{
  "count": 2,
  "hits": [
    {
      "id": 1,
      "group": 2,
      "profile": {
        "name": "Willie Gomez",
        "email": "wgomez@immuta.com",
        "phone": null,
        "about": null,
        "location": null,
        "organization": null,
        "position": null,
        "preferences": {
          "tabDataSourceState": 1,
          "tabProjectState": 1
        },
        "hdfsUser": "wgomez",
        "id": 3,
        "createdAt": "2018-07-05T07:37:06.373Z",
        "updatedAt": "2018-07-05T07:37:06.373Z"
      },
      "createdAt": "2015-08-23T00:00:00.000Z",
      "updatedAt": "2018-07-05T07:37:07.283Z",
      "userid": "wgomez@immuta.com",
      "iamid": "bim"
    },
    {
      "id": 2,
      "group": 2,
      "profile": {
        "name": "Helen James",
        "email": "hjames@immuta.com",
        "phone": null,
        "about": null,
        "location": null,
        "organization": null,
        "position": null,
        "preferences": null,
        "hdfsUser": null,
        "id": 13,
        "createdAt": "2018-07-05T07:37:06.470Z",
        "updatedAt": "2018-07-05T07:37:06.470Z"
      },
      "createdAt": "2018-07-05T07:37:07.291Z",
      "updatedAt": "2018-07-05T07:37:07.291Z",
      "userid": "hjames@immuta.com",
      "iamid": "bim"
    }
  ]
}

Delete a group

Endpoint

Method Path Purpose
DELETE /bim/group/{groupId} Delete the specified group.

Query Parameters

Attribute Description Required
groupId integer The group ID. Yes

Response Parameters

None.

Request example

This request will delete the group with the ID 3.

curl \
    --request DELETE \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/group/3

Authenticate a user and create a project API key

Endpoint

Method Path Purpose
POST /bim/apikey Authenticate the user and create a project API key.

Request Parameters

None.

Payload Parameters

Attribute Description Required
projectId integer The project ID. No
name string The name to associate with the API key. No

The payload must have one or both of the two attributes above.

Response Parameters

Attribute Description
apikey string The new API key.
keyid integer The new API key's ID.
project integer The project ID.
name string The name of the API key.

Request example

This example request with the payload below will authenticate the user Jane Doe in the project with the ID 1 and create a new API key for her.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/bim/apikey

Payload example

{
  "projectId": 1,
  "name": "My Project API Key"
}

Response example

{
  "apikey": "******",
  "keyid": 334,
  "project": 1,
  "name": "My Project API Key",
  "context": null
}

Authenticate with an API key

Method Path Purpose
POST /bim/apikey/authenticate Authenticate with the Immuta API using an API key.
POST /bim/apikey/impersonate Impersonate another user using an API key.

Authenticate a user with an API key

Endpoint

Method Path Purpose
POST /bim/apikey/authenticate Authenticate with the Immuta API using an API key.

Request Parameters

None.

Payload Parameters

Attribute Description
apikey string The API key.

Response Parameters

Attribute Description
authenticated boolean If true, the user has been successfully authenticated.
token string The user's access token.

Request example

This example request will authenticate the user with the Immuta API.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/bim/apikey/authenticate
Payload example
{
  "apikey": "100874dyour-api-key-79aa38bbfe0e8c787"
}

Response example

{
  "authenticated": true,
  "token": "be420************2745ea0307"
}

Impersonate a user with an API key

Endpoint

Method Path Purpose
POST /bim/apikey/impersonate Impersonate another user using an API key.

Request Parameters

None.

Payload Parameters

Attribute Description
apikey string The API key of the account with the user impersonation permission.
userid string The username of the impersonated user.
iamid string The IAM ID of the impersonated user.
projectId integer The project ID of the impersonated user.

Response Parameters

Attribute Description
authenticated boolean If true, the user has been successfully authenticated.
token string The user's access token.

Request example

This example request will allow the requesting user to impersonate the user specified in example-payload.json.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/bim/apikey/impersonate
Payload example
{
  "apikey": "requesting-users-api-key",
  "userid": "user1@example.com",
  "iamid": "bim"
}

Response example

{
  "authenticated": true,
  "token": "0753*************c61d2"
}

View tokens and API keys

Method Path Purpose
POST /bim/token Get information for a given token, should it exist.
GET /bim/iam/{iamid}/user/{userid}/apikeys Get metadata for all of the user's API Keys.

View token information

Endpoint

Method Path Purpose
POST /bim/token Get information for a given token, should it exist.

Request Parameters

None.

Payload Parameters

Attribute Description
token string The access token.

Response Parameters

Attribute Description
id integer The access token ID.
type string The token type: bearer.
iamid string The IAM ID.
userid string The user's username.
project integer If the token was generated using a project API key, this is the project ID.
token string The access token.
created timestamp The date the token was created.
lastUsed timestamp The date the token was last used.
expiration timestamp The date the token will expire.
name string The token name.
createdAt timestamp The date the token was created.
updatedAt timestamp The date the token was last updated.
scopes string The scope of the token, such as impersonation.
impersonationuserid string The user ID of the impersonating user.
impersonationiamid string The IAM ID of the impersonating user.

Request example

This example request will return information on the access token in the payload.

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example-payload.json \
  https://demo.immuta.com/bim/token
Payload example
{
  "token": "48983da*********85220837d"
}

Response example

{
  "id": 384,
  "type": "bearer",
  "iamid": "bim",
  "userid": "jane.doe@immuta.com",
  "project": null,
  "context": null,
  "token": "4898*********220837d",
  "created": "2021-10-15T03:59:03.000Z",
  "lastUsed": "2021-10-15T03:59:57.185Z",
  "expiration": "2021-10-15T04:59:57.185Z",
  "name": null,
  "application": null,
  "derivedFrom": null,
  "createdAt": "2021-10-15T03:59:03.562Z",
  "updatedAt": "2021-10-15T03:59:57.186Z",
  "scopes": null,
  "impersonationuserid": null,
  "impersonationiamid": null
}

View a user's API keys

Endpoint

Method Path Purpose
GET /bim/iam/{iamid}/user/{userid}/apikeys Get metadata for all of the user's API keys.

Request Parameters

Attribute Description Required
iamid string The IAM ID. Yes
userid string The user's username. Yes

Response Parameters

Attribute Description
keyid integer The API key ID.
created timestamp The date the API key was created.
project array Information on the project attached to the API key, including values for name, status, description, documentation, deleted, allowMaskedJoins, subscriptionType, subscriptionPolicy, equalization, snowflake, salt, type, schema, id, createdAt, updatedAt, workspace, createdBy, updatedBy, and schemaEvolutionId.
lastUsed timestamp The date the API key was last used.
name string The API key name.

Request example

This example request will return information on the API keys of the user with the username john.doe@immuta.com.

curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/iam/bim/user/john.doe%40immuta.com/apikeys

Response example

[
  {
    "keyid": 323,
    "created": "2021-10-06T18:28:13.000Z",
    "project": {
      "projectKey": "Credit Payments",
      "name": "Credit Payments",
      "status": "open",
      "description": "This project contains all data sources under the schema, credit_payments, from admin@snowflake.demo-databases.prod.immuta.com:3306/credit_payments.",
      "documentation": "This is an automatically generated project that collects data sources under the schema, credit_payments, from admin@snowflake.demo-databases.prod.immuta.com:3306/credit_payments. When data sources in this schema are added to the system, they will automatically be added to this project.",
      "deleted": false,
      "allowMaskedJoins": false,
      "subscriptionType": "manual",
      "subscriptionPolicy": null,
      "equalization": null,
      "snowflake": null,
      "salt": "e0c4a8c5-2a5b-4488-9c43-cb3d816172f4",
      "type": "Schema",
      "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

Endpoint

Method Path Purpose
DELETE /bim/apikey/{keyid} Delete an API key, all auth tokens issued using that API key, and generate a new API key.

Request Parameters

Attribute Description Required
keyid integer The API key ID. Yes

Response Parameters

Attribute Description
revokedTokens integer The number of tokens revoked.

Request example

This example request will delete the API key with the ID 323, revoke all the auth tokens issued using that API key, and generate a new API key.

curl \
  --request DELETE \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://demo.immuta.com/bim/apikey/323

Response example

{
  "revokedTokens": 1
}