Skip to main content

How to Manage Account IAM Roles

Account IAM Roles allow you to grant your AWS IAM roles access to download report files directly from Lumar's S3 bucket. This is useful for integrating Lumar data into your own data pipelines without needing to use signed URLs.

Overview​

When you register an IAM role with your Lumar account:

  1. The role ARN is validated to ensure it follows the correct AWS IAM role ARN format
  2. A bucket policy statement is added to Lumar's reports S3 bucket granting the role s3:GetObject and s3:ListBucket permissions
  3. Access is scoped to only your account's data (files prefixed with account_{accountId}/)

Limits​

  • Maximum of 5 IAM roles per account
  • Role ARN must match the pattern: arn:aws:iam::{12-digit-account-id}:role/{role-name}

Prerequisites​

Before registering an IAM role, ensure:

  1. You have Admin role access to the Lumar account
  2. Your AWS IAM role exists and is configured with the appropriate trust policy
  3. Your IAM role ARN is in the correct format

Creating an Account IAM Role​

Use the createAccountIamRole mutation to register an IAM role with your account.

mutation CreateAccountIamRole($input: CreateAccountIamRoleInput!) {
  createAccountIamRole(input: $input) {
    entity {
      id
      roleArn
      createdAt
      updatedAt
    }
  }
}

Try in explorer

Input Fields​

FieldTypeRequiredDescription
accountIdObjectIDYesThe ID of the account to add the IAM role to
roleArnStringYesThe full ARN of the AWS IAM role

Error Handling​

The mutation may return the following errors:

  • AccountIamRolesLimitReached - Maximum of 5 IAM roles per account has been reached
  • AccountIamRoleAlreadyExists - The role ARN is already registered to this account
  • InvalidIamRoleArn - The role ARN format is invalid
  • AccountIamRolePolicyUpdateFailed - Failed to update the S3 bucket policy

Listing Account IAM Roles​

Query the iamRoles connection on an Account to list all registered IAM roles.

query GetAccountIamRoles($accountId: ObjectID!) {
  getAccount(id: $accountId) {
    id
    name
    iamRoles(first: 10) {
      totalCount
      nodes {
        id
        roleArn
        createdAt
        updatedAt
      }
    }
  }
}

Try in explorer

Deleting an Account IAM Role​

Use the deleteAccountIamRole mutation to remove an IAM role from your account. This will revoke the role's access to the S3 bucket.

mutation DeleteAccountIamRole($input: DeleteAccountIamRoleInput!) {
  deleteAccountIamRole(input: $input) {
    entity {
      id
      roleArn
    }
  }
}

Try in explorer

Using the IAM Role​

Once registered, your IAM role can directly access report download files in Lumar's S3 bucket. The files are located at:

s3://deepcrawl-dc-reports-prod-1/account_{accountId}/{report-files}

Your role will have permissions to:

  • List objects with the prefix account_{accountId}/
  • Get objects under account_{accountId}/

Example: AWS CLI​

# List your account's report files
aws s3 ls s3://deepcrawl-dc-reports-prod-1/account_715/ --profile your-assumed-role

# Download a specific report file
aws s3 cp s3://deepcrawl-dc-reports-prod-1/account_715/report.csv ./report.csv --profile your-assumed-role

Example: AWS SDK (Node.js)​

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: "us-east-1" });

const response = await s3.send(
  new GetObjectCommand({
    Bucket: "deepcrawl-dc-reports-prod-1",
    Key: "account_715/report.csv",
  }),
);