Skip to content

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

Authorizations

Search Authorizations

Searches across all existing authorizations with the provided query string.

Method Path Response
GET /bim/authorizations 200 application/json

Request Parameters

  • search(string): The string used to search for existing authorizations.
  • iamid(string): Optionally provide the IAM to filter the authorizations.
  • type(string): Filter by the given type.

Example Request

curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    https://demo.immuta.com/bim/authorizations?search=loc

Example Response

[
  {
    "iamid": "bim",
    "type": "auth",
    "value": "location"
  },
  {
    "iamid": "bim",
    "type": "auth",
    "value": "locality"
  }
]