Skip to main content

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)ACCESSPERMISSION
All Apps And ResourcesREADfullReadAccess
Shared: QuestionsREADreadQuestions
GraphDataREADreadGraph
LandingREADaccessLanding
AssetsREADaccessAssets
PoliciesREADaccessPolicies
ComplianceREADaccessCompliance
AlertsREADaccessRules
GraphViewerREADaccessGalaxy
InsightsREADaccessInsights
IntegrationsREADaccessIntegrations
Endpoint ComplianceREADaccessEndpointCompliance

Permission Strings: ADMIN

DISPLAY NAME (J1 APP)ACCESSPERMISSION
All Apps And ResourcesADMINaccessAdmin
Shared: QuestionsADMINwriteQuestions
GraphDataADMINwriteGraph
LandingADMINadminLanding
AssetsADMINadminAssets
PoliciesADMINadminPolicies
ComplianceADMINadminCompliance
AlertsADMINadminRules
GraphViewerADMINadminGalaxy
InsightsADMINadminInsights
IntegrationsADMINadminIntegrations
Endpoint ComplianceADMINadminEndpointCompliance
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

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)[];
}

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)ACCESSPERMISSION
All Apps And ResourcesREADfullReadAccess
Shared: QuestionsREADreadQuestions
GraphDataREADreadGraph
LandingREADaccessLanding
AssetsREADaccessAssets
PoliciesREADaccessPolicies
ComplianceREADaccessCompliance
AlertsREADaccessRules
GraphViewerREADaccessGalaxy
InsightsREADaccessInsights
IntegrationsREADaccessIntegrations
Endpoint ComplianceREADaccessEndpointCompliance

Permission Strings: ADMIN

DISPLAY NAME (J1 APP)ACCESSPERMISSION
All Apps And ResourcesADMINaccessAdmin
Shared: QuestionsADMINwriteQuestions
GraphDataADMINwriteGraph
LandingADMINadminLanding
AssetsADMINadminAssets
PoliciesADMINadminPolicies
ComplianceADMINadminCompliance
AlertsADMINadminRules
GraphViewerADMINadminGalaxy
InsightsADMINadminInsights
IntegrationsADMINadminIntegrations
Endpoint ComplianceADMINadminEndpointCompliance
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"
}
}
}