IAM operations

note

accessAdmin permission is required for all IAM operations.

Endpoint:

POST https://graphql.us.jupiterone.io/

Headers:

Content-Type: application/json
Accept: application/json
JupiterOne-Account: {Account_ID}
Authorization: Bearer {API_Key}

Get IAM groups

Query: iamGroups

Retrieves all account groups within the query limit.

limit: (required) max number of records to return
cursor: (optional) continuation token

query Query($limit: Int!, $cursor: String) {
  iamGroups(limit: $limit, cursor: $cursor) {
    items {
      id
      name
      description
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

API Samples

Sample (S1): iamGroups

(S1): Request

{
  "limit": 5
}

(S1): Response

{
  "data": {
    "iamGroups": {
      "items": [
        {
          "id": "12c2d370-89ef-4280-970b-d520ca1837be",
          "name": "Users",
          "description": ""
        },
        {
          "id": "dd354c7a-1b9b-4579-ac5e-873fe3b2c851",
          "name": "Administrators",
          "description": "Admin users"
        }
      ],
      "pageInfo": {
        "endCursor": "eyJhY2NvdW50I...",
        "hasNextPage": true
      }
    }
  }
}

Get Users of IAM group

Query: iamGroupUsers

Retrieves all group members of the specified group (by id) within the query limit.

groupId: (required) unique group identifier
limit: (required) max number of records to return
cursor: (optional) continuation token
Note: The item.id property in the response is the JupiterOne uid.

query Query($groupId: String!, $limit: Int!, $cursor: String) {
  iamGroupUsers(groupId: $groupId, limit: $limit, cursor: $cursor) {
    items {
      id
      email
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

API Samples

Sample (S1): iamGroupUsers

(S1): Request

{
  "groupId": "22c2d370-89ef-4280-970b-d520ca1837be",
  "limit": 5
}

(S1): Response

{
  "data": {
    "iamGroupUsers": {
      "items": [
        {
          "id": "222xxx222_abc",
          "email": "abc@mycompany.com"
        },
        {
          "id": "222xxx222_def@mycompany.com",
          "email": "def@mycompany.com"
        }
      ],
      "pageInfo": {
        "endCursor": "eyJ1c2VyIjoiaj...",
        "hasNextPage": true
      }
    }
  }
}

Add IAM User to Group

Mutation: addIamUserToGroupByEmail

Adds a user to a group using the specified email and group ID.

groupId: (required)
userEmail: (required)

mutation Mutation($groupId: String!, $userEmail: String!) {
  addIamUserToGroupByEmail(groupId: $groupId, userEmail: $userEmail) {
    success
  }
}

API Samples

Sample (S1): addIamUserToGroupByEmail

(S1): Request

{
  "groupId": "22c2d370-89ef-4280-970b-d520ca1837be",
  "userEmail": "abc@mycompany.com"
}

(S1): Response

{
  "data": {
    "addIamUserToGroupByEmail": {
      "success": true
    }
  }
}

Remove IAM user from group

Mutation: removeIamUserFromGroupByEmail

Removes a user from a group using the specified email and group ID.

groupId: (required)
userEmail: (required)

mutation Mutation($groupId: String!, $userEmail: String!) {
  removeIamUserFromGroupByEmail(groupId: $groupId, userEmail: $userEmail) {
    success
  }
}

API Samples

Sample (S1): removeIamUserFromGroupByEmail

(S1): Request

{
  "groupId": "22c2d370-89ef-4280-970b-d520ca1837be",
  "userEmail": "xyz@mycompany.com"
}

(S1): Response

{
  "data": {
    "removeIamUserFromGroupByEmail": {
      "success": true
    }
  }
}

Create IAM Group

Mutation: createIamGroup

Creates a new group with a specified name and optionally: description, queryPolicy, and/or abacPermissions.

name: (required) must be unique to all other groups.
description: (optional)
abacPermissions: (optional)
queryPolicy: (optional)

mutation Mutation(
  $name: String!
  $description: String
  $abacPermissions: [String!]
  $queryPolicy: [JSON!]
) {
  createIamGroup(
    name: $name
    description: $description
    abacPermissions: $abacPermissions
    queryPolicy: $queryPolicy
  ) {
    id
    name
    description
  }
}

API Type Definitions

queryPolicy

Description: Group Query Policies define query access for members of a particular group. Setting this property via the IAM API will overwrite any existing queryPolicy for the given group. If updating this property, always define the full queryPolicy to enforce.

Type: list of JSON objects with primitive values or an array or primitive values.

type queryPolicy = [JSON!];
type JSON = {
  [key: string]: string | number | boolean || (string | number | boolean)[];
}

queryPolicy

abacPermissions

ABAC permissions define application access for members of a perticular group. Setting this property via the IAM API will overwrite any existing permissions for the given group. If updating this property, always define the full list of permissions that should be granted.

Type: list of valid permission strings (see table below).

type abacPermissions = [permission!]
type permission = string // must be a valid permission string

Permission Strings: READ-ONLY

DISPLAY NAME (J1 APP)	ACCESS	PERMISSION
All Apps And Resources	READ	`fullReadAccess`
Shared: Questions	READ	`readQuestions`
GraphData	READ	`readGraph`
Home Page	READ	`accessLanding`
Assets	READ	`accessAssets`
Policies	READ	`accessPolicies`
Compliance	READ	`accessCompliance`
Alerts	READ	`accessRules`
GraphViewer	READ	`accessGalaxy`
Insights	READ	`accessInsights`
Integrations	READ	`accessIntegrations`
Endpoint Compliance	READ	`accessEndpointCompliance`

Permission Strings: ADMIN

DISPLAY NAME (J1 APP)	ACCESS	PERMISSION
All Apps And Resources	ADMIN	`accessAdmin`
Shared: Questions	ADMIN	`writeQuestions`
GraphData	ADMIN	`writeGraph`
Home Page	ADMIN	`adminLanding`
Assets	ADMIN	`adminAssets`
Policies	ADMIN	`adminPolicies`
Compliance	ADMIN	`adminCompliance`
Alerts	ADMIN	`adminRules`
GraphViewer	ADMIN	`adminGalaxy`
Insights	ADMIN	`adminInsights`
Integrations	ADMIN	`adminIntegrations`
Endpoint Compliance	ADMIN	`adminEndpointCompliance`
ENABLE API KEY ACCESS	*	`apiKeyUser`

API Samples

Sample (S1): createIamGroup

(S1): Request

{
  "name": "Users"
}

(S1): Response

{
  "data": {
    "createIamGroup": {
      "id": "90909-11ef-4280-970b-4444ca1837be",
      "name": "Users"
    }
  }
}

Sample (S2): createIamGroup

(S2): Request

{
  "name": "UsersX",
  "description": "A group for X users"
}

(S2): Response

{
  "data": {
    "createIamGroup": {
      "id": "11c2d370-89ef-4280-970b-d520ca1837be",
      "name": "UsersX",
      "description": "A group for X users"
    }
  }
}

Sample (S3): createIamGroup

(S3): Request

{
  "name": "Support",
  "description": "A group for support users",
  "queryPolicy": [
    {
      "_type": ["aws_ecr_image", "bitbucket_pullrequest"]
    }
  ]
}

(S3): Response

{
  "data": {
    "createIamGroup": {
      "id": "23434-454-45656-65656-4564564565",
      "name": "Support",
      "description": "A group for support users"
    }
  }
}

Sample (S4): createIamGroup

(S4): Request

{
  "name": "Admins",
  "queryPolicy": [
    {
      "_type": "aws_ecs_task_definition",
      "_class": "Account"
    },
    {
      "_type": "aws_ecr_image"
    }
  ]
}

(S4): Response

{
  "data": {
    "createIamGroup": {
      "id": "87787-6787-678678-778-6786786",
      "name": "Admins"
    }
  }
}

Access All Actions and Resources

You can use an API token to access all actions and resources

Update IAM Group

Mutation: updateIamGroup

Updates a group's properties: name, description, queryPolicy, and/or abacPermissions.

id: (required) must tie to an existing group.
name: (optional) must be unique to all other groups.
description: (optional)
abacPermissions: (optional)
queryPolicy: (optional)

mutation Mutation(
  $id: String!
  $name: String
  $description: String
  $abacPermissions: [String!]
  $queryPolicy: [JSON!]
) {
  updateIamGroup(
    id: $id
    name: $name
    description: $description
    abacPermissions: $abacPermissions
    queryPolicy: $queryPolicy
  ) {
    id
    name
    description
  }
}

API Type Definitions

queryPolicy

Type: list of JSON objects with primitive values or an array or primitive values.

type queryPolicy = [JSON!];
type JSON = {
  [key: string]: string | number | boolean || (string | number | boolean)[];
}

abacPermissions

Description: ABAC permissions define application access for members of a perticular group. Setting this property via the IAM API will overwrite any existing permissions for the given group. If updating this property, always define the full list of permissions that should be granted.

Type: list of valid permission strings (see table below).

type abacPermissions = [permission!];
type permission = string; // must be a valid permission string

Permission Strings: READ-ONLY

DISPLAY NAME (J1 APP)	ACCESS	PERMISSION
All Apps And Resources	READ	`fullReadAccess`
Shared: Questions	READ	`readQuestions`
GraphData	READ	`readGraph`
Home Page	READ	`accessLanding`
Assets	READ	`accessAssets`
Policies	READ	`accessPolicies`
Compliance	READ	`accessCompliance`
Alerts	READ	`accessRules`
GraphViewer	READ	`accessGalaxy`
Insights	READ	`accessInsights`
Integrations	READ	`accessIntegrations`
Endpoint Compliance	READ	`accessEndpointCompliance`

Permission Strings: ADMIN

DISPLAY NAME (J1 APP)	ACCESS	PERMISSION
All Apps And Resources	ADMIN	`accessAdmin`
Shared: Questions	ADMIN	`writeQuestions`
GraphData	ADMIN	`writeGraph`
Home Page	ADMIN	`adminLanding`
Assets	ADMIN	`adminAssets`
Policies	ADMIN	`adminPolicies`
Compliance	ADMIN	`adminCompliance`
Alerts	ADMIN	`adminRules`
GraphViewer	ADMIN	`adminGalaxy`
Insights	ADMIN	`adminInsights`
Integrations	ADMIN	`adminIntegrations`
Endpoint Compliance	ADMIN	`adminEndpointCompliance`
ENABLED API KEY ACCESS	*	`apiKeyUser`

API Samples

Sample (S1): updateIamGroup

(S1): Request

{
  "id": "90909-11ef-4280-970b-4444ca1837be",
  "name": "Users"
}

(S1): Response

{
  "data": {
    "updateIamGroup": {
      "id": "90909-11ef-4280-970b-4444ca1837be",
      "name": "Users",
      "description": "original description.."
    }
  }
}

Sample (S2): updateIamGroup

(S2): Request

{
  "id": "90909-11ef-4280-970b-4444ca",
  "name": "UsersX",
  "description": "A group for X users"
}

(S2): Response

{
  "data": {
    "updateIamGroup": {
      "id": "90909-11ef-4280-970b-4444ca",
      "name": "UsersX",
      "description": "A group for X users"
    }
  }
}

Sample (S3): updateIamGroup

(S3): Request

{
  "id": "90909-11ef-4280-970b-4444ca",
  "abacPermissions": ["accessPolicies", "writeQuestions", "accessGalaxy"],
  "queryPolicy": [
    {
      "_type": "aws_ecs_task_definition"
    }
  ]
}

(S3): Response

{
  "data": {
    "updateIamGroup": {
      "id": "90909-11ef-4280-970b-4444ca",
      "name": "UsersX",
      "description": "A group for X users"
    }
  }
}

Sample (S4): updateIamGroup

(S4): Request

{
  "id": "90909-11ef-4280-970b-4444ca",
  "description": "allow account class",
  "queryPolicy": [
    {
      "_type": "aws_ecs_task_definition",
      "_class": "Account"
    },
    {
      "_integrationType": ["whitehat"]
    }
  ]
}

(S4): Response

{
  "data": {
    "updateIamGroup": {
      "id": "90909-11ef-4280-970b-4444ca",
      "name": "UsersX",
      "description": "allow account class"
    }
  }
}

Get IAM groups​

Get Users of IAM group​

Add IAM User to Group​

Remove IAM user from group​

Create IAM Group​

Update IAM Group​

Contents

Get IAM groups

Get Users of IAM group

Add IAM User to Group

Remove IAM user from group

Create IAM Group

Update IAM Group