Skip to content

Trigger Analysis Partner Account

This API supports several use cases where partners want to trigger analysis of an account's IAM configuration:

You can trigger an analysis for a partner-managed account using the k9 API with:

POST /partner/{partner_id}/customer/{partner_customer_id}/account/{account_id}/analysis

To simplify adoption, this API only requires information the partner already has so that the partner does not need to, e.g. maintain a mapping of the partner's Customer ID to the k9 Customer ID.

When you successfully trigger an account analysis, k9 will immediately return an execution id. k9 will deliver the analysis to the secure inbox configured for the partner or customer account once it is complete. An incremental analysis generally takes at least 10 minutes for small accounts and up to 2 hours for large accounts.

Request Headers

Set the Content-Type header to application/json

Request Path Parameters

The account analysis API requires three path parameters:

partner_id: the k9 Partner ID that manages the account to analyze, e.g. P123456. k9 Security will provide the Partner ID to the partner.

Type: String

Pattern: P[\d]{6}

partner_customer_id: the partner's own unique customer or tenant identifier for the managed customer environment, e.g. a UUID, AWS Organization ID, SHA256 digest

Type: String

Pattern: [\w-_.]{6,64}

account_id: the AWS account ID to analyze, e.g. 123456789012

Type: String

Pattern: [\d]{12}

Request Body

Populate the request body with a json document like:

{
  "partnerId": "{partner_id}",
  "partnerCustomerId": "{partner_customer_id}",
  "accountId": "{account_id}"
}

Note that while this body currently duplicates information from the request path, we plan to allow you to scope the analysis request to specific principals and resources in the future.

Response

Success

When you successfully trigger an account analysis, the API will respond with:

Response Status Code: 202 (Accepted)

Response Body (Example):

{
  "partnerId": "{partner_id}",
  "partnerCustomerId": "{partner_customer_id}",
  "customerId": "{customer_id}",
  "accountId": "{account_id}",
  "executionId": "ondemand-{customer_id}-{account_id}-{START_YYYY-MM-DD}_{RANDSTR}"
}

The response contains information confirming the analysis request was accepted.

The customerId is the automatically managed k9 Customer ID that the partner's Customer ID is mapped to within k9. The customerId for partner-managed accounts has the form {partner_id}-{12-digit zero-padded number}

Example customerId: P123456-430363089266

The executionId is a token the caller can use to identify this analysis. The executionId is meant to be opaque to machines, but useful to people. It identifies the analysis' k9 Customer ID, AWS account ID, the date the analysis was started (UTC), and a random 4-character suffix.

Example executionId: ondemand-P123456-430363089266-123456789012-2022-11-11_ONO2.

Not Authorized

If the calling principal is not authorized to trigger an analysis, the API will respond with:

Response Status Code: 403 (Forbidden)

Response Body (Example):

{
  "message": "Caller is not authorized to trigger analysis for k9 partnerId (P123456) and partnerCustomerId (550e8400-e29b-41d4-a716-446655440000)"
}

Last update: May 20, 2024