Immuta Identity and Access Management HTTP API

Audience: System Administrators

Content Summary: The built-in IAM HTTP API allows users to programmatically access information about users, their group memberships, and authorizations. Most of the actions described here require ADMIN permissions.

Identity and Access Managers

Identity and access managers are the back-ends that drive authentication, and optionally group membership and authorizations for users in Immuta.

Get IAMs

Gets a listing of configured IAM services.

Method	Path	Response
GET	`/bim/iam`	200 application/json

Example Request

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

Example Response

[
  {
    "id": "bim",
    "displayName": "Immuta",
    "type": "built-in",
    "oauth": false
  },
  {
    "id": "github",
    "displayName": "Github",
    "type": "github",
    "oauth": true
  },
  {
    "id": "ldap",
    "displayName": "LDAP",
    "type": "ldap"
  }
]

Users

Current User

The current user endpoint returns the user profile information for the authenticated user.

Method	Path	Response
GET	`/bim/rpc/user/current`	200 application/json

Example Request

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

Example Response

{
  "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"
}

Search Users

Administrative search over the aggregated view of all users. This includes users from all configured IAMs.

Method	Path	Response
GET	`/bim/user`	200 application/json

Request Parameters

name(string): A partial name to match against user names.
userid(string): A partial ID to match against user IDs.
email(string): A partial email address to match against user email addresses.
iamid([]string): Optionally provide the IAM to filter the users.
excludeSystemGenerated(boolean): Optionally exclude accounts automatically created for handlers that periodically crawl and ingest.
includeDisabled(boolean): Optionally include disabled users.
size(integer: 25): The maximum number of records to return.
offset(integer): Offset to start returning values.
sortField(string): The field to sort results on. Defaults to user name. Possible values: name, createdAt, iamid, email.
sortOrder(string: asc): The order that the results will be sorted in. Possible values: asc, desc.

Response Parameters

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 ([]object): List of result objects.

Example Request

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

Example Response

{
  "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"
    }
  ]
}

Get User

Gets the specified user's aggregated view. The response includes:

Profile
Permissions
Authorizations

Method	Path	Response
GET	`/bim/iam/{iamid}/user/{userid}`	200 application/json

Request Path Parameters

iamid(string): The IAM the user belongs to.
userid(string): The ID of the user to return.

Example Request

curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/iam/bim/user/bspringer%40immuta.com

Example Response

{
  "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"
}

Get User Groups

Gets the specified user's list of groups.

Method	Path	Response
GET	`/bim/iam/{iamid}/user/{userid}/groups`	200 application/json

Request Path Parameters

iamid(string): The IAM the user belongs to.
userid(string): The ID of the user to return.

Example Request

curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/iam/bim/user/bspringer%40immuta.com/groups

Example Response

[
  {
    "id": 2,
    "name": "engineers",
    "iamid": "bim",
    "groupUser": 2
  }
]

Groups

Search Groups

Gets the list of groups from all configured IAMs. This includes groups from all configured IAMs.

Method	Path	Response
GET	`/bim/group`	200 application/json

Request Parameters

name(string): A partial name to match against group names.
iamid([]string): Optionally provide the IAM to filter the groups.
size(integer: 25): The maximum number of records to return.
offset(integer): Offset to start returning values.
sortField(string): The field to sort results on. Defaults to name. Possible values: name, createdAt, iamid.
sortOrder(string: asc): The order that the results will be sorted in. Possible values: asc, desc.

Response Parameters

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 ([]object): List of result objects.

Example Request

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

Example Response

{
  "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"
    }
  ]
}

Get Group

Gets the specified group.

Method	Path	Response
GET	`/bim/group/{groupid}`	200 application/json

Request Path Parameters

groupid(integer): The ID of the group.

Example Request

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

Example Response

{
  "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"
}

Get Group Users

Gets the users in the specified group.

Method	Path	Response
GET	`/bim/group/{groupid}/user`	200 application/json

Request Path Parameters

groupid(integer): The ID of the group.

Request Query Parameters

offset(integer): Offset to start returning values.
size(integer: 25): The maximum number of records to return.
sortOrder(string: asc): The order that the results will be sorted in. Possible values: asc, desc.

Example Request

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

Example Response

{
  "count": 2,
  "hits": [
    {
      "id": 1,
      "group": 2,
      "profile": {
        "name": "Willie Gomez",
        "email": "wgmoez@immuta.com",
        "phone": null,
        "about": null,
        "location": null,
        "organization": null,
        "position": null,
        "preferences": {
          "tabDataSourceState": 1,
          "tabProjectState": 1
        },
        "hdfsUser": "wgmoez",
        "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"
    }
  ]
}