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. Usesize
andoffset
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. Usesize
andoffset
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"
}
]
}