CreateMembers
Sends a request to invite the specified AWS accounts to be member accounts in the behavior graph. This operation can only be called by the master account for a behavior graph.
CreateMembers
verifies the accounts and then sends invitations to the
verified accounts.
The request provides the behavior graph ARN and the list of accounts to invite.
The response separates the requested accounts into two lists:
-
The accounts that
CreateMembers
was able to start the verification for. This list includes member accounts that are being verified, that have passed verification and are being sent an invitation, and that have failed verification. -
The accounts that
CreateMembers
was unable to process. This list includes accounts that were already invited to be member accounts in the behavior graph.
Request Syntax
POST /graph/members HTTP/1.1
Content-type: application/json
{
"Accounts": [
{
"AccountId": "string
",
"EmailAddress": "string
"
}
],
"GraphArn": "string
",
"Message": "string
"
}
URI Request Parameters
The request does not use any URI parameters.
Request Body
The request accepts the following data in JSON format.
- Accounts
-
The list of AWS accounts to invite to become member accounts in the behavior graph. For each invited account, the account list contains the account identifier and the AWS account root user email address.
Type: Array of Account objects
Array Members: Minimum number of 1 item. Maximum number of 50 items.
Required: Yes
- GraphArn
-
The ARN of the behavior graph to invite the member accounts to contribute their data to.
Type: String
Pattern:
^arn:aws[-\w]{0,10}?:detective:[-\w]{2,20}?:\d{12}?:graph:[abcdef\d]{32}?$
Required: Yes
- Message
-
Customized message text to include in the invitation email message to the invited member accounts.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1000.
Required: No
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"Members": [
{
"AccountId": "string",
"DisabledReason": "string",
"EmailAddress": "string",
"GraphArn": "string",
"InvitedTime": number,
"MasterId": "string",
"PercentOfGraphUtilization": number,
"PercentOfGraphUtilizationUpdatedTime": number,
"Status": "string",
"UpdatedTime": number
}
],
"UnprocessedAccounts": [
{
"AccountId": "string",
"Reason": "string"
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- Members
-
The set of member account invitation requests that Detective was able to process. This includes accounts that are being verified, that failed verification, and that passed verification and are being sent an invitation.
Type: Array of MemberDetail objects
- UnprocessedAccounts
-
The list of accounts for which Detective was unable to process the invitation request. For each account, the list provides the reason why the request could not be processed. The list includes accounts that are already member accounts in the behavior graph.
Type: Array of UnprocessedAccount objects
Errors
For information about the errors that are common to all actions, see Common Errors.
- InternalServerException
-
The request was valid but failed because of a problem with the service.
HTTP Status Code: 500
- ResourceNotFoundException
-
The request refers to a nonexistent resource.
HTTP Status Code: 404
- ServiceQuotaExceededException
-
This request cannot be completed for one of the following reasons.
-
The request would cause the number of member accounts in the behavior graph to exceed the maximum allowed. A behavior graph cannot have more than 1000 member accounts.
-
The request would cause the data rate for the behavior graph to exceed the maximum allowed.
-
Detective is unable to verify the data rate for the member account. This is usually because the member account is not enrolled in Amazon GuardDuty.
HTTP Status Code: 402
-
- ValidationException
-
The request parameters are invalid.
HTTP Status Code: 400
Examples
Example
This example illustrates one usage of CreateMembers.
Sample Request
PUT /graph/members HTTP/1.1
Host: api.detective.us-west-2.amazonaws.com
Accept-Encoding: identity
Content-Length: 442
Authorization: AUTHPARAMS
X-Amz-Date: 20200123T193018Z
User-Agent: aws-cli/1.14.29 Python/2.7.9 Windows/8 botocore/1.8.33
{
"Accounts": [
{
"AccountId": "444455556666",
"EmailAddress": "mmajor@example.com"
},
{
"AccountId": "123456789012",
"EmailAddress": "jstiles@example.com"
}
],
"GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899",
"Message": "This is Paul Santos. I need to add your account to the data we use for security investigation in Detective. If you have any questions, contact me at psantos@example.com."
}
Example
This example illustrates one usage of CreateMembers.
Sample Response
HTTP/1.1 200 OK
Content-Length: 625
Date: Thu, 23 Jan 2020 23:07:46 GMT
x-amzn-RequestId: 397d0549-0092-11e8-a0ee-a7f9aa6e7572
Connection: Keep-alive
{
"Members": [
{
"AccountId": "444455556666",
"EmailAddress": "mmajor@example.com",
"GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899",
"InvitedTime": 1579826107000,
"MasterId": "111122223333",
"Status": "INVITED",
"UpdatedTime": 1579826107000
},
{
"AccountId": "123456789012",
"EmailAddress": "jstiles@example.com",
"GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899",
"InvitedTime": 1579826107000,
"MasterId": "111122223333",
"Status": "VERIFICATION_IN_PROGRESS",
"UpdatedTime": 1579826107000
}
],
"UnprocessedAccounts": [ ]
}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: